nvim-laurel 🌿

A set of macros for Neovim config
inspired by the builtin Nvim Lua-Vimscript bridge on metatable and by good old Vim script

Warning

Some breaking changes are planned until v1.0.0.
COOKBOOK.md contains how to update them as painlessly as possible; see REFERENCE.md for usage of g:laurel_deprecated, which would also help you update them as long as they are deprecated, but not abolished yet.

Documentations

• The Reference lists out the nvim-laurel interfaces. Note that the interfaces are not limited to Fennel macros.
• The Cookbook demonstrates practical codes on the nvim-laurel interfaces.
• The Appendix shows extra knowledge not limited to nvim-laurel, but useful to write nvim config files in Fennel: LSP, Treesitter, etc. Happy Coding!
• The Changelog. See also the Cookbook for tips how to update features and usages deprecated or removed in nvim-laurel.

Design

• Fast: Each macro is expanded to a few nvim API functions in principle.
• Less: The syntax is as little, but flexible and extensible as possible.
• Fzf-Friendly: Options such as desc, buffer, expr, ..., can be set in sequential table instead of key-value table. In this format, options are likely to be formatted into the same line where nvim-laurel macro starts from.

Requirements

• Neovim 0.9.5+
• A compiler: Fennel, hotpot.nvim, etc.

Installation

With a compiler plugin (recommended)

1. Add nvim-laurel to 'runtimepath', before registering it with your plugin manager, to use nvim-laurel macros as early as possible.

   With lazy.nvim

   local function prerequisite(name, url)
     -- To manage the version of repo, the path should be where your plugin manager will download it.
     local name = url:gsub("^.*/", "")
     local path = vim.fn.stdpath("data") .. "/lazy/" .. name
     if not vim.loop.fs_stat(path) then
       vim.fn.system({
         "git",
         "clone",
         "--filter=blob:none",
         url,
         path,
       })
     end
     vim.opt.runtimepath:prepend(path)
   end
   
   -- Install your favorite plugin manager.
   prerequisite("https://github.com/folke/lazy.nvim")
   
   -- Install nvim-laurel
   prerequisite("https://github.com/aileot/nvim-laurel")
   
   -- Install a runtime compiler
   prerequisite("https://github.com/rktjmp/hotpot.nvim")
   
   require("hotpot").setup({
     compiler = {
       macros = {
         env = "_COMPILER",
         allowedGlobals = false,
         -- Comment out below to use `os`, `vim`, etc. at compile time,
         -- but UNRECOMMENDED with nvim-laurel.
         -- compilerEnv = _G,
       },
     },
   })
   
   -- Then, you can write config in Fennel with nvim-laurel.
   require("your.core")

   With dein.vim

   local function prerequisite(url)
     -- To manage the version of repo, the path should be where your plugin manager will download it.
     local path = "~/.cache/dein/repos/" .. url:gsub("^.*://", "")
     if not vim.loop.fs_stat(path) then
       vim.fn.system({
         "git",
         "clone",
         "--filter=blob:none",
         url,
         path,
       })
     end
     vim.opt.runtimepath:prepend(path)
   end
   
   -- Install your favorite plugin manager.
   prerequisite("https://github.com/Shougo/dein.vim")
   
   -- Install nvim-laurel
   prerequisite("https://github.com/aileot/nvim-laurel")
   
   -- Install a runtime compiler
   prerequisite("https://github.com/rktjmp/hotpot.nvim")
   
   require("hotpot").setup({
     compiler = {
       macros = {
         env = "_COMPILER",
         allowedGlobals = false,
       },
     },
   })
   
   -- Then, you can write config in Fennel with nvim-laurel.
   require("your.core")

2. Manage the version of nvim-laurel by your favorite plugin manager. It's recommended to specify a version range to avoid unexpected breaking changes.

   With lazy.nvim,

   require("lazy.nvim").setup({
     {
       "aileot/nvim-laurel", {
       -- v0.7.1 <= {version} < v0.8.0
       -- Note: v0.7.0 has a backward compatibility issue.
       version = "~v0.7.1",
     },
     ... -- and other plugins
   }, {
       defaults = {
         lazy = true,
       },
       performance = {
         rtp = {
           -- Note: Not to remove nvim-laurel from &rtp, and not to encounter any
           -- other potential issues, it's UNRECOMMENDED to reset &rtp unless you
           -- don't mind the extra cost to maintain the "paths" properly.
           reset = false,
         }
       }
     })

   or, if you are confident in writing plugin specs in Fennel,

   (local lazy (require :lazy))
   (lazy.setup [{1 :aileot/nvim-laurel
                 ;; v0.7.1 <= {version} < v0.8.0
                 ;; Note: v0.7.0 has a backward compatibility issue.
                 :version "~v0.7.0"
                ...] ;; and other plugins
               {:defaults {:lazy true
                           ;; Note: Not to remove nvim-laurel from &rtp, and not to encounter any
                           ;; other potential issues, it's UNRECOMMENDED to reset &rtp unless you
                           ;; don't mind the extra cost to maintain the "paths" properly.
                           :performance {:rtp {:reset false}}}})

   With dein.vim in toml,

   [[plugins]]
   repo = "aileot/nvim-laurel"
   # Note: v0.7.0 has a backward compatibility issue.
   rev = "v0.7.*"

To compile outside Neovim

1. Download nvim-laurel where you feel like

   git clone https://github.com/aileot/nvim-laurel /path/to/install

2. Compile your fennel files with macro path and package path for nvim-laurel. For example, in your Makefile,

   %.lua: %.fnl
     fennel \
       --add-macro-path "/path/to/nvim-laurel/fnl/?.fnl;/path/to/nvim-laurel/fnl/?/init.fnl" \
       --add-package-path "/path/to/nvim-laurel/lua/?.lua;/path/to/nvim-laurel/lua/?/init.lua" \
       --compile $< > $@

3. Add /path/to/nvim-laurel to 'runtimepath' in your Neovim config file.

   vim.opt.rtp:append("/path/to/nvim-laurel")

Usage

(import-macros {: set! : map! : augroup! : au! ...} :laurel.macros)

See REFERENCE.md for each macro usage in details.

Macro List

• Autocmd

  • augroup!
  • autocmd!
  • au!

• Keymap

  • map!: A replacement of vim.keymap.set
  • unmap!: A replacement of vim.keymap.del
  • <Cmd>
  • <C-u>

• Option

  • let!
  • set!
  • setglobal!
  • setlocal!
  • go!
  • bo!
  • wo!

• Variable

  • g!
  • b!
  • w!
  • t!
  • v!
  • env!

• Others

  • command!
  • feedkeys!
  • highlight!
  • hi!

Alternatives

• aniseed
• hibiscus.nvim
• katcros-fnl
• nvim-anisole-macros
• nyoom.nvim
• themis.nvim
• zest.nvim