🛰️ 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++
Fennel
Go
Html
Java
Javascript (and jsx)
JSON
Lua
Ocaml
Php
Python
Ruby
Rust
TOML
Typescript (and tsx)
Verilog
YAML

⚡️ Requirements

Neovim >= 0.5.0
nvim-treesitter

📦 Installation

Install the plugin with your preferred package manager:

packer

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

vim-plug

" 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.

-- Lua

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

-- 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"] = ' '
			}
		},
		["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"] = ' '
			}
		},

		-- 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
	-- Note: to make use of depth feature properly, make sure your separator isn't something that can appear
	-- in context names (eg: function names, class names, etc)
	depth = 0,

	-- indicator used when context is 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.

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

Few examples below

feline

example feline setup

-- 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
})

galaxyline

example galaxyline setup

-- 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
	}
}

lualine

example lualine setup

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

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

vimscript

example setup using native vim way

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

set statusline+=%{NvimGps()}

windline

example windline setup

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

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

🔥 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!

wookayin / nvim-gps