Home

Awesome

hlargs.nvim

Highlight arguments' definitions and usages, asynchronously, using Treesitter

Preview

BeforeAfter
beforeafter

hlargs vs LSP semantic tokens

Neovim 0.9 officially added support for LSP semantic tokens. These offer a much more complete and precise form of highlighting than hlargs. These two methods can coexist, for example by using hlargs for the languages where LSP tokens are not available, or they are available but don't define special highlight groups for arguments (check out :h hlargs-lsp for an example).

Some advantages of hlargs are:

Installation

This plugin is for neovim only. Version 0.7+ is recommended. If you are using 0.6, use the branch 0.6-compat and an appropriate nvim-treesitter version (installation instructions in the README of that branch).

For nvim versions <0.9, nvim-treesitter is a required dependency. For 0.9 or higher, it is not necessary (though it's highly recommended, to install the parsers)

lazy.nvim

return {
    'm-demare/hlargs.nvim',
}

packer.nvim:

use { 'm-demare/hlargs.nvim' }

vim-plug:

Plug 'm-demare/hlargs.nvim'

Usage

If you are ok with the default settings:

require('hlargs').setup()

To change the settings:

require('hlargs').setup {
  color = '#ef9062',
  highlight = {},
  excluded_filetypes = {},
  disable = function(lang, bufnr) -- If changed, `excluded_filetypes` will be ignored
    return vim.tbl_contains(opts.excluded_filetypes, lang)
  end,
  paint_arg_declarations = true,
  paint_arg_usages = true,
  paint_catch_blocks = {
    declarations = false,
    usages = false
  },
  extras = {
    named_parameters = false,
  },
  hl_priority = 120,
  excluded_argnames = {
    declarations = {},
    usages = {
      python = { 'self', 'cls' },
      lua = { 'self' }
    }
  },
  performance = {
    parse_delay = 1,
    slow_parse_delay = 50,
    max_iterations = 400,
    max_concurrent_partial_parses = 30,
    debounce = {
      partial_parse = 3,
      partial_insert_mode = 100,
      total_parse = 700,
      slow_parse = 5000
    }
  }
}
-- (You may omit the settings whose defaults you're ok with)

To understand the performance settings see performance. The other settings should be self explainatory

After setup, the plugin will be enabled. You can enable/disable/toggle it using:

require('hlargs').enable()
require('hlargs').disable()
require('hlargs').toggle()

Dynamically change color

If you want to change the color dynamically, according to filetype or whatever, you can do that using the highlight group Hlargs

Supported languages

Currently these languages are supported

Note that you have to install each language's parser using :TSInstall {lang}

jsx parser gets installed with the javascript one, but tsx parser is independent from the typescript one

Request new language

Please include a sample file with your request, that covers most of the edge cases that specific language allows for (nested functions, lambda functions, member functions, parameter destructuring, optional parameters, rest paratemeters, etc). See examples.

Also do note that I can't support a language that doesn't have a Treesitter parser implemented. Check here

Performance

This plugin uses a combination of incremental and total parsing, to achieve both great speed and consistent highlighting results. It works as follows:

The results of these 3 types of tasks are merged in order to always show the most up to date information

There are a couple of settings that let you adjust performance to your own use case. I recommend only playing with them if you are having some specific issue, otherwise the defaults should work fine