⚠️ Deprecated! Use nvim-navic instead of this plugin

nvim-navic is an improved version of nvim-gps (a version 2.0!). It accompishes the same task as this plugin, but uses LSP instead of Treesitter. It also adds ability to have coloured icons!

🛰️ nvim-gps

Take this handy dandy gps with you on your coding adventures and always know where you are!

🤔 What is nvim-gps?

nvim-gps is a simple status line component that shows context of the current cursor position in file. It is similar to the statusline function provided by nvim-treesitter, but smarter. Using custom treesitter queries for each language, nvim-gps is able to show exact name of containing class, struct, function, method, etc. along with some fancy symbols!

Here is a barebones example how it looks in a statusline

Here is a example of how it can look in a fully configured statusline

✅ Supported Languages

• Bash (and Zsh)
• C
• C++
• C#
• Fennel
• Go
• Haskell
• Html
• Java
• Javascript (and jsx)
• JSON
• LaTeX
• Lua
• Norg
• Nix
• Ocaml
• Php
• Python
• Ruby
• Rust
• TOML
• Typescript (and tsx)
• Verilog
• YAML
• YANG
• Zig

⚡️ Requirements

• Neovim >= 0.5.0
• nvim-treesitter

📦 Installation

Install the plugin with your preferred package manager:

packer

luaCopy
-- Lua
use {
	"SmiteshP/nvim-gps",
	requires = "nvim-treesitter/nvim-treesitter"
}

vim-plug

vimCopy
" Vimscript
Plug "nvim-treesitter/nvim-treesitter"
Plug "SmiteshP/nvim-gps"

⚙️ Configuration

nvim-gps provides a setup function that takes in a table with configuration options.
The default configuration assumes that you are using a nerd font.

Note: setup function needs to be called once for nvim-gps to work.

luaCopy
-- Lua

-- Default config
require("nvim-gps").setup()

luaCopy
-- Lua

-- Customized config
require("nvim-gps").setup({

	disable_icons = false,           -- Setting it to true will disable all icons

	icons = {
		["class-name"] = ' ',      -- Classes and class-like objects
		["function-name"] = ' ',   -- Functions
		["method-name"] = ' ',     -- Methods (functions inside class-like objects)
		["container-name"] = '⛶ ',  -- Containers (example: lua tables)
		["tag-name"] = '炙'         -- Tags (example: html tags)
	},

	-- Add custom configuration per language or
	-- Disable the plugin for a language
	-- Any language not disabled here is enabled by default
	languages = {
		-- Some languages have custom icons
		["json"] = {
			icons = {
				["array-name"] = ' ',
				["object-name"] = ' ',
				["null-name"] = '[] ',
				["boolean-name"] = 'ﰰﰴ ',
				["number-name"] = '# ',
				["string-name"] = ' '
			}
		},
		["latex"] = {
			icons = {
				["title-name"] = "# ",
				["label-name"] = " ",
			},
		},
		["norg"] = {
			icons = {
				["title-name"] = " ",
			},
		},
		["toml"] = {
			icons = {
				["table-name"] = ' ',
				["array-name"] = ' ',
				["boolean-name"] = 'ﰰﰴ ',
				["date-name"] = ' ',
				["date-time-name"] = ' ',
				["float-name"] = ' ',
				["inline-table-name"] = ' ',
				["integer-name"] = '# ',
				["string-name"] = ' ',
				["time-name"] = ' '
			}
		},
		["verilog"] = {
			icons = {
				["module-name"] = ' '
			}
		},
		["yaml"] = {
			icons = {
				["mapping-name"] = ' ',
				["sequence-name"] = ' ',
				["null-name"] = '[] ',
				["boolean-name"] = 'ﰰﰴ ',
				["integer-name"] = '# ',
				["float-name"] = ' ',
				["string-name"] = ' '
			}
		},
		["yang"] = {
			icons = {
				["module-name"] = " ",
				["augment-path"] = " ",
				["container-name"] = " ",
				["grouping-name"] = " ",
				["typedef-name"] = " ",
				["identity-name"] = " ",
				["list-name"] = "﬘ ",
				["leaf-list-name"] = " ",
				["leaf-name"] = " ",
				["action-name"] = " ",
			}
		},

		-- Disable for particular languages
		-- ["bash"] = false, -- disables nvim-gps for bash
		-- ["go"] = false,   -- disables nvim-gps for golang

		-- Override default setting for particular languages
		-- ["ruby"] = {
		--	separator = '|', -- Overrides default separator with '|'
		--	icons = {
		--		-- Default icons not specified in the lang config
		--		-- will fallback to the default value
		--		-- "container-name" will fallback to default because it's not set
		--		["function-name"] = '',    -- to ensure empty values, set an empty string
		--		["tag-name"] = ''
		--		["class-name"] = '::',
		--		["method-name"] = '#',
		--	}
		--}
	},

	separator = ' > ',

	-- limit for amount of context shown
	-- 0 means no limit
	depth = 0,

	-- indicator used when context hits depth limit
	depth_limit_indicator = ".."
})

🚀 Usage

nvim-gps doesn't modify your statusline by itself, instead you are provided with two functions and it is left up to you to incorporate them into your statusline.

luaCopy
-- Lua
local gps = require("nvim-gps")

gps.is_available()  -- Returns boolean value indicating whether a output can be provided
gps.get_location()  -- Returns a string with context information (or nil if not available)

-- example output: "mystruct > sum"

<details> <summary> You can also pass optional arguments to <code>get_location</code> function to override options given in setup function: </summary>

luaCopy
opts = {
	disable_icons = false,
	separator = ' > ',
	depth = 0,
	depth_limit_indicator = ".."
}

gps.get_location(opts)

</details>

These two functions should satisfy the needs of most users, however if you want the raw intermediate data for custom usage you can use the following function:

luaCopy
gps.get_data()      -- Returns a table of intermediate representation of data (which is used by get_location)
                    -- Table of tables that contain 'text', 'type' and 'icon' for each context

<details> <summary>An example output of <code>get_data</code> function: </summary>

luaCopy
 {
 	{
		text = "mystruct",
		type = "class-name",
		icon = " "
	},
	{
		text = "sum",
		type = "method-name",
		icon = " "
	}
 }

</details>

Examples of Integrating with Other Plugins

feline

<details> <summary>An example feline setup </summary>

luaCopy
-- Lua
local gps = require("nvim-gps")

table.insert(components.active[1], {
	provider = function()
		return gps.get_location()
	end,
	enabled = function()
		return gps.is_available()
	end
})

</details>

galaxyline

<details> <summary>An example galaxyline setup </summary>

luaCopy
-- Lua
local gps = require("nvim-gps")

require('galaxyline').section.left[1]= {
	nvimGPS = {
		provider = function()
			return gps.get_location()
		end,
		condition = function()
			return gps.is_available()
		end
	}
}

</details>

lualine

<details> <summary>An example lualine setup </summary>

luaCopy
-- Lua
local gps = require("nvim-gps")

require("lualine").setup({
	sections = {
			lualine_c = {
				{ gps.get_location, cond = gps.is_available },
			}
	}
})

</details>

vimscript

<details> <summary> example setup using native vim way </summary>

vimCopy
" vimscript
func! NvimGps() abort
	return luaeval("require'nvim-gps'.is_available()") ?
		\ luaeval("require'nvim-gps'.get_location()") : ''
endf

set statusline+=%{NvimGps()}

</details>

windline

<details> <summary> example windline setup </summary>

luaCopy
-- Lua
local gps = require("nvim-gps")

comps.gps = {
	function()
		if gps.is_available() then
			return gps.get_location()
		end
		return ''
	end,
	{"white", "black"}
}

</details>

🔥 Contributions

Is your favorite language not supported? Or did you find something not being captured by the nvim-gps? Please consider opening a issue, or even better make a PR and solve the issue!! 😄

Please read the CONTRIBUTING.md to understand how the treesitter queries work and how you can add/enhance the queries for your favorite programming languages!