nvim-laurel 🌿

A set of Fennel 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: nvim-thyme, hotpot.nvim, etc., or Fennel itself.

📦 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.

   local function bootstrap(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.
   bootstrap("https://github.com/folke/lazy.nvim")
   
   -- Install nvim-laurel
   bootstrap("https://github.com/aileot/nvim-laurel")
   
   -- Install a runtime compiler: nvim-thyme
   bootstrap("https://git.sr.ht/~technomancy/fennel")
   bootstrap("https://github.com/aileot/nvim-thyme")
   table.insert(package.loaders, function(...)
     return require("thyme").loader(...) -- Make sure to `return` the result!
   end)
   -- Note: Add a cache path to &rtp. The path MUST include the literal substring "/thyme/compile".
   local thyme_cache_prefix = vim.fn.stdpath("cache") .. "/thyme/compiled"
   vim.opt.rtp:prepend(thyme_cache_prefix)
   
   --[[ For hotpot.nvim instead of nvim-thyme
   bootstrap("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")

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}}}})

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 detail.

🔥 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, but compiles into vim.api.nvim_set_keymap.
  • unmap!: A replacement of vim.keymap.del, but compiles into vim.api.nvim_del_keymap.
  • <Cmd>
  • <C-u>

• Option

  • let!: A replacement of vim.opt, vim.opt_local, vim.opt_global, vim.o, vim.bo, vim.wo, but compiles into vim.api.nvim_set_option_value.
  • set!: A let! alternative dedicated to handle Vim option value like vim.opt.
  • setglobal! A let! alternative dedicated to handle Vim global option value like vim.opt_global.
  • setlocal! A let! alternative dedicated to handle Vim local option value like vim.opt_local.

• Variable

  • g!: A let! alternative dedicated to handle Vim global variable vim.g.
  • b!: A let! alternative dedicated to handle Vim buffer-local variable vim.b.
  • w!: A let! alternative dedicated to handle Vim window-local variable vim.w.
  • t!: A let! alternative dedicated to handle Vim tabpage-local variable vim.t.
  • v!: A let! alternative dedicated to handle Vim variable vim.v.
  • env!: A let! alternative dedicated to handle environment variable vim.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