modeline.nvim

A Neovim specific plugin for handling modelines.

Getting started

lazy.nvim

{
    "CheesyChocolate/modeline.nvim",
    config = function()
        require('modeline').setup()
    end
}

Usage

Add a modeline to the first or last 5 lines of any file, prefixed with nvim:, to have it automatically executed when an LSP client attaches to that buffer.

Syntax

The modeline syntax is designed to feel like a familiar command-line interface.

nvim: Command1 [args] ; Command2 [args]

• Commands are separated by a semicolon ;.
• Arguments are space-separated and can be one of three types:
  • Positional Arguments: Simple values (lua_ls, tsserver).
  • Flags: Boolean switches prefixed with -- (--force).
  • Key-Value Arguments: Settings with an equals sign (tabstop=4).

Default Handlers

• LspStop: Stops LSP clients.

  -- Stop the lua_ls and tsserver LSP clients
  -- nvim: LspStop lua_ls tsserver
  
  -- Stop all running clients, with force
  -- nvim: LspStop --force all

Configuration

The setup() function accepts a table where you can define your own handlers or override the default ones.

Handlers are functions that receive a single args table, which is structured by the parser.

require('modeline').setup({
    handlers = {
        -- Override the default LspStop handler
        LspStop = function(args)
            print("Custom LspStop called!")
            -- args.flags.force will be true if --force was used
            -- args.positional will be a list of client names
            -- You can still call the original handler if you want
            require('modeline.handlers.lsp').LspStop(args)
        end,

        -- Add a new, custom handler
        SetOption = function(args)
            -- nvim: SetOption tabstop=4 softtabstop=4
            for key, value in pairs(args.kv) do
                vim.opt_local[key] = value
            end
        end,
    }
})