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. (The version would be released after nvim v1.0.)
If you encounter breaking changes and the deprecation notices that precede them, COOKBOOK.md will help you update 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!: A replacement of vim.api.nvim_create_augroup
  • autocmd!: A replacement of vim.api.nvim_create_autocmd
  • au!: An alias of autocmd!

• Keymap

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

• Option

  • let!: A replacement of vim.opt, vim.opt_local, vim.opt_global, vim.o, vim.bo, vim.wo.
    You can wrap this macro into set!, setlocal!, ..., set+, set-, ..., bo!, wo!, and so on.
    Follow the links for the details.

• Variable

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

• Others

  • command!: A replacement of vim.api.nvim_create_user_command
  • feedkeys!
  • highlight!
  • hi!

Alternatives

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