Take this handy dandy gps with you on your coding adventures and always know where you are!
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
- Bash (and Zsh)
- C
- C++
- C#
- Fennel
- Go
- Html
- Java
- Javascript (and jsx)
- JSON
- LaTeX
- Lua
- Norg
- Ocaml
- Php
- Python
- Ruby
- Rust
- TOML
- Typescript (and tsx)
- Verilog
- YAML
- YANG
- Zig
- Neovim >= 0.5.0
- nvim-treesitter
Install the plugin with your preferred package manager:
-- Lua
use {
"SmiteshP/nvim-gps",
requires = "nvim-treesitter/nvim-treesitter"
}" Vimscript
Plug "nvim-treesitter/nvim-treesitter"
Plug "SmiteshP/nvim-gps"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:
setupfunction 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"] = ' '
}
},
["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 = ".."
})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 You can also pass optional arguments to get_location function to override options given in setup function
opts = {
disable_icons = false,
separator = ' > ',
depth = 0,
depth_limit_indicator = ".."
}
gps.get_location(opts)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
gps.get_data() -- Returns an intermediate representation of data (which is used by get_location)
-- Table of tables that contain 'text', 'type' and 'icon' for each context example output of get_data function
{
{
text = "mystruct",
type = "class-name",
icon = " "
},
{
text = "sum",
type = "method-name",
icon = " "
}
}Few examples below
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
})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
}
}example lualine setup
-- Lua
local gps = require("nvim-gps")
require("lualine").setup({
sections = {
lualine_c = {
{ gps.get_location, cond = gps.is_available },
}
}
})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()}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"}
}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!