nvf

Autocommands and Autogroups

This module allows you to declaratively configure Neovim autocommands and autogroups within your Nix configuration.

Autogroups (vim.augroups)

Autogroups (augroup) organize related autocommands. This allows them to be managed collectively, such as clearing them all at once to prevent duplicates. Each entry in the list is a submodule with the following options:

Option Type Default Description Example
enable bool true Enables or disables this autogroup definition. true
name str None Required. The unique name for the autogroup. "MyFormatGroup"
clear bool true Clears any existing autocommands within this group before adding new ones defined in vim.autocmds. true

Example:

{
  vim.augroups = [
    {
      name = "MyCustomAuGroup";
      clear = true; # Clear previous autocommands in this group on reload
    }
    {
      name = "Formatting";
      # clear defaults to true
    }
  ];
}

Autocommands (vim.autocmds)

Autocommands (autocmd) trigger actions based on events happening within Neovim (e.g., saving a file, entering a buffer). Each entry in the list is a submodule with the following options:

Option Type Default Description Example
enable bool true Enables or disables this autocommand definition. true
event nullOr (listOf str) null Required. List of Neovim events that trigger this autocommand (e.g., BufWritePre, FileType). [ "BufWritePre" ]
pattern nullOr (listOf str) null List of file patterns (globs) to match against (e.g., *.py, *). If null, matches all files for the given event. [ "*.lua", "*.nix" ]
callback nullOr luaInline null A Lua function to execute when the event triggers. Use lib.nvim.types.luaInline or lib.options.literalExpression "mkLuaInline '''...'''". Cannot be used with command. lib.nvim.types.luaInline "function() print('File saved!') end"
command nullOr str null A Vimscript command to execute when the event triggers. Cannot be used with callback. "echo 'File saved!'"
group nullOr str null The name of an augroup (defined in vim.augroups) to associate this autocommand with. "MyCustomAuGroup"
desc nullOr str null A description for the autocommand (useful for introspection). "Format buffer on save"
once bool false If true, the autocommand runs only once and then automatically removes itself. false
nested bool false If true, allows this autocommand to trigger other autocommands. false

Warning

You cannot define both callback (for Lua functions) and command (for Vimscript) for the same autocommand. Choose one.

Examples:

{ lib, ... }:
{
  vim.augroups = [ { name = "UserSetup"; } ];

  vim.autocmds = [
    # Example 1: Using a Lua callback
    {
      event = [ "BufWritePost" ];
      pattern = [ "*.lua" ];
      group = "UserSetup";
      desc = "Notify after saving Lua file";
      callback = lib.nvim.types.luaInline ''
        function()
          vim.notify("Lua file saved!", vim.log.levels.INFO)
        end
      '';
    }

    # Example 2: Using a Vim command
    {
      event = [ "FileType" ];
      pattern = [ "markdown" ];
      group = "UserSetup";
      desc = "Set spellcheck for Markdown";
      command = "setlocal spell";
    }

    # Example 3: Autocommand without a specific group
    {
      event = [ "BufEnter" ];
      pattern = [ "*.log" ];
      desc = "Disable line numbers in log files";
      command = "setlocal nonumber";
      # No 'group' specified
    }

    # Example 4: Using Lua for callback
    {
      event = [ "BufWinEnter" ];
      pattern = [ "*" ];
      desc = "Simple greeting on entering a buffer window";
      callback = lib.generators.mkLuaInline ''
        function(args)
          print("Entered buffer: " .. args.buf)
        end
      '';
      
      # Run only once per session trigger
      once = true; 
    }
  ];
}

These definitions are automatically translated into the necessary Lua code to configure vim.api.nvim_create_augroup and vim.api.nvim_create_autocmd when Neovim starts.