hlargs.txt

*hlargs.txt* Highlight arguments' definitions and usages, using Treesitter
*hlargs.nvim*

Author: Matías Demare <https://github.com/m-demare>
Homepage: <https://github.com/m-demare/hlargs.nvim>
License: GNU GPL v3.0

==============================================================================
USAGE                                                           *hlargs-usage*

Calling `setup` is required for the plugin to work. After calling it, it will
be enabled by default, it can be enabled, disabled or toggled as follows:
>lua
    require('hlargs').setup()
    require('hlargs').enable()
    require('hlargs').disable()
    require('hlargs').toggle()
    require('hlargs').enable_buf(bufnr)
    require('hlargs').disable_buf(bufnr)
<

Calling setup with no arguments will use the default settings. You can pass a
table with the settings you want to override. The defaults are the following:

>lua
    require('hlargs').setup {
      color = '#ef9062',
      use_colorpalette = false,
      colorpalette = {
        { fg = "#ef9062" },
        { fg = "#3AC6BE" },
        { fg = "#35D27F" },
        { fg = "#EB75D6" },
        { fg = "#E5D180" },
        { fg = "#8997F5" },
        { fg = "#D49DA5" },
        { fg = "#7FEC35" },
        { fg = "#F6B223" },
        { fg = "#F67C1B" },
        { fg = "#DE9A4E" },
        { fg = "#BBEA87" },
        { fg = "#EEF06D" },
        { fg = "#8FB272" },
      },
      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 = 10000,
      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
        }
      }
    }
<

==============================================================================
API                                                               *hlargs-api*

These methods are available in |require('hlargs').*|

enable_buf                                                 *hlargs-enable-buf*
    Description: Enable highlighting for given buffer number.
    Parameters:
        bufnr:
            type: number
            default: Current buffer

disable_buf                                               *hlargs-disable-buf*
    Description: Disable highlighting for given buffer number.
    Parameters:
        bufnr:
            type: number
            default: Current buffer
==============================================================================
CONFIGURATION                                                  *hlargs-config*

This section describes the configuration fields which can be passed to
|hlargs.setup()|. The settings table is merged with the defaults using
vim.tbl_deep_extend (giving priority to user's settings), so you only have to
change the settings you want to differ.

For performance related configurations, see |hlargs-performance|

color                                                    *hlargs-config-color*
    Description: Hex color to be applied to arguments. Used if `highlight` is
    an empty table and ignored if `highlight` is not an empty table (and
    `highlight` will be used).
    Type: `string`
    Default: '#ef9062'

use_colorpalette                              *hlargs-config-use_colorpalette*
    Description: If you want multiple colors for arguments.
    Type: `bool`
    Default: `false`

colorpalette                                     *hlargs-config-colorpalette*
    Description: Hex colors to be applied to arguments. If
    `use_colorpalette` is `true` it will be used. There will be added
    `Hlarg{idx}` highlight group `Hlarg{idx}` where `{idx}` is index of
    `colorpalette` and `idx` calculate by polynomial rolling hash function
    Type: `table[]`
    Default:
>lua
    {
        { fg = "#ef9062" },
        { fg = "#3AC6BE" },
        { fg = "#35D27F" },
        { fg = "#EB75D6" },
        { fg = "#E5D180" },
        { fg = "#8997F5" },
        { fg = "#D49DA5" },
        { fg = "#7FEC35" },
        { fg = "#F6B223" },
        { fg = "#F67C1B" },
        { fg = "#DE9A4E" },
        { fg = "#BBEA87" },
        { fg = "#EEF06D" },
        { fg = "#8FB272" },
      }
<

highlight                                            *hlargs-config-highlight*
    Description: Highlights to be applied to arguments, see |nvim_set_hl|.
    Type: `table`
    Default: `{}`

excluded_filetypes                          *hlargs-config-excluded_filetypes*
    Description: Specify filetypes to be excluded. Ignored if `disable` is
    changed
    Type: `string[]`
    Default: `{}`

disable                                                *hlargs-config-disable*
    Description: Function that decides if a given language/buffer should be
    ignored. Return `true` to disable, `false` to enable.
    Type: `function`
    Default:
>lua
        disable = function(lang, bufnr)
            return vim.tbl_contains(opts.excluded_filetypes, lang)
        end
<

paint_arg_declarations                  *hlargs-config-paint_arg_declarations*
    Description: Whether argument declarations should be colored or not
    Type: `bool`
    Default: `true`

paint_arg_usages                              *hlargs-config-paint_arg_usages*
    Description: Whether argument usages should be colored or not
    Type: `bool`
    Default: `true`

paint_catch_blocks                          *hlargs-config-paint_catch_blocks*
    Description: Whether catch block arguments (exceptions) should be
    colored or not.
    Type: `table`
    Default:
>lua
    {
        declarations = false,
        usages = false
    }
<

extras                                                  *hlargs-config-extras*
    Description: Extra syntactic highlighting (handled by |treesitter-highlight|)
    Type: `table`
    Default:
>lua
    {
        named_parameters = false,
    }
<

hl_priority                                        *hlargs-config-hl_priority*
    Description: Priority for highlighting
    Type: `number`
    Default: 10000

excluded_argnames                            *hlargs-config-excluded_argnames*
    Description: Some languages use keywords that you may not want highlighted
    (for example, `self` in python). You can exclude their declarations, their
    usages or both. Feel free to sugest if we should add another
    language/keyword by default.
    Type: `table`
    Default:
>lua
    {
        declarations = {},
        usages = {
            python = { 'self', 'cls' },
            lua = { 'self' }
        }
    }
<


==============================================================================
CUSTOMIZATION                                               *hlargs-customize*

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


==============================================================================
PERFORMANCE                                               *hlargs-performance*

This plugin uses a combination of incremental and total parsing, to achieve
both great speed and consistent highlighting results. It works as follows:
- When a new buffer is opened, or when a file is externally modified, a total
  parse task is launched. This is CPU intensive, but should rarely happen
- When the buffer is modified, a partial task is launched for every modified
  group of lines (identifying the region that should be parsed depending on
  what was modified), up to `max_concurrent_partial_parses`. If this is
  exceeded (e.g. by a big find and replace), a total parse task is launched.
  Partial tasks are extremely fast/lightweight, allowing for real time
  highlighting with barely any CPU impact. However, it is not 100% precise, in
  some weird edge cases it might miss some usages. Hence, upon every change,
  with a big debouncing, a "slow" task is launched
- Slow tasks are the same as total tasks, except they are throttled on purpose
  so that they use basically 0 CPU. The idea is that partial tasks are
  generally very precise, so these just run in the background when needed to
  fix some of the small imprecisions that might be left

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:


parse_delay                                               *hlargs-parse_delay*
    Description: Is the time between parsing iterations, left for vim to
    compute other events. Longer means less CPU load, but slower parsing
    Type: `number`
    Default: 1
    Unit: ms

slow_parse_delay                                     *hlargs-slow_parse_delay*
    Description: Is the same as `parse_delay`, but for slow tasks. I should be
    set in a value such that CPU usage from slow parses is negligible
    Type: `number`
    Default: 50
    Unit: ms

max_iterations                                         *hlargs-max_iterations*
    Description: Is the maximum amount of functions it will parse. The main
    objective of this is that it doesn't waste too much time parsing huge
    minified files, but you can set it lower if your PC struggles with smaller
    files
    Type: `number`
    Default: 400

max_concurrent_partial_parses           *hlargs-max_concurrent_partial_parses*
    Description: Is the maximum amount of partial parsing tasks allowed. If the
    limit is exceeded, no more partial tasks will launch, and instead a single
    total task will be used
    Type: `number`
    Default: 30

debounce                                                     *hlargs-debounce*
    Description: defines debouncing time for each kind of task. The idea is
    that when multiple changes happen in a short amount of time, overlapping
    changes can be merged into a single task. If you don't want real time
    highlighting in insert mode, you can increase this to 1-2 seconds
    Type: `table`
    Unit: ms
    Default:
>lua
        {
            partial_parse = 3,
            partial_insert_mode = 100,
            total_parse = 700,
            slow_parse = 5000
        }
<
==============================================================================
LSP                                                               *hlargs-lsp*

Hlargs can be enabled/disabled per buffer, which allows it to easily coexist
with LSP semantic tokens. The following is a snippet to disable Hlargs if a
language server with semantic token capabilities is attached to a buffer
(credit to @perrin4869 for the snippet):
>lua
    vim.api.nvim_create_augroup("LspAttach_hlargs", {clear = true})
    vim.api.nvim_create_autocmd("LspAttach", {
      group = "LspAttach_hlargs",
      callback = function(args)
        if not (args.data and args.data.client_id) then
          return
        end

        local client = vim.lsp.get_client_by_id(args.data.client_id)
        local caps = client.server_capabilities
        if caps.semanticTokensProvider and caps.semanticTokensProvider.full then
          require("hlargs").disable_buf(args.buf)
        end
      end,
    })
<

vim:tw=78:et:ft=help:norl: