https://github.com/aileot/nvim-laurel
🌿 A set of macros for Neovim, highly inspired by Vim script, and Nvim Lua-Vimscript bridge on metatable
https://github.com/aileot/nvim-laurel
fennel macro nvim nvim-plugin
Last synced: about 2 months ago
JSON representation
🌿 A set of macros for Neovim, highly inspired by Vim script, and Nvim Lua-Vimscript bridge on metatable
- Host: GitHub
- URL: https://github.com/aileot/nvim-laurel
- Owner: aileot
- License: mit
- Created: 2021-11-30T02:03:05.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-11T22:01:13.000Z (10 months ago)
- Last Synced: 2024-12-11T22:31:23.015Z (10 months ago)
- Topics: fennel, macro, nvim, nvim-plugin
- Language: Fennel
- Homepage:
- Size: 709 KB
- Stars: 29
- Watchers: 1
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# nvim-laurel 🌿
[![badge/test][]][url/to/workflow/test] [![badge/semver][]][url/to/semver]
[![badge/license][]][url/to/license]\
_A set of Fennel macros for Neovim config_\
_inspired by the builtin Nvim Lua-Vimscript bridge on metatable_ _and by good
old Vim script_
[![badge/fennel][]][url/to/fennel]
[badge/test]: https://img.shields.io/github/actions/workflow/status/aileot/nvim-laurel/test.yml?branch=main&label=Test&logo=github&style=for-the-badge&logo=neovim&logoColor=CDD6F4&labelColor=1E1E2E&color=a6e3a1
[badge/semver]: https://img.shields.io/github/v/release/aileot/nvim-laurel?style=for-the-badge&logo=starship&logoColor=CDD6F4&labelColor=1E1E2E&&color=cdd6f4&include_prerelease&sort=semver
[badge/license]: https://img.shields.io/github/license/aileot/nvim-laurel?style=for-the-badge&logoColor=CDD6F4&labelColor=1E1E2E&color=89dceb
[badge/fennel]: https://img.shields.io/badge/Powered_by_Fennel-030281?&style=for-the-badge&logo=lua&logoColor=cdd6f4&label=Lua&labelColor=1E1E2E&color=cba6f7
[url/to/workflow/test]: https://github.com/aileot/nvim-laurel/actions/workflows/test.yml
[url/to/license]: ./LICENSE
[url/to/semver]: https://github.com/aileot/nvim-laurel/releases/latest
[url/to/fennel]: https://fennel-lang.org/
> [!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](./docs/cookbook.md) will help you update as painlessly as
> possible; see [REFERENCE.md](./docs/reference.md) for usage of
> [`g:laurel_deprecated`](./docs/reference.md#glaurel_deprecated), which would
> also help you update them as long as they are deprecated, but not abolished
> yet.
## 📚 Documentations
- The [Reference](./docs/reference.md) lists out the nvim-laurel interfaces.
Note that the interfaces are not limited to Fennel macros.
- The [Cookbook](./docs/cookbook.md) demonstrates practical codes on the
nvim-laurel interfaces.
- The [Appendix](./docs/appendix.md) shows extra knowledge not limited to
nvim-laurel, but useful to write nvim config files in Fennel: LSP, Treesitter,
etc. Happy Coding!
- The [Changelog](./docs/changelog.md). _See also the
[Cookbook](./docs/cookbook.md)_ 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 `format`ted into the same line where nvim-laurel macro starts
from.
## ✔️ Requirements
- Neovim 0.9.5+
- A compiler: [nvim-thyme][nvim-thyme],
[hotpot.nvim][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.
```lua
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](https://github.com/folke/lazy.nvim),
```lua
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,
```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
```sh
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,
```make
%.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.
```lua
vim.opt.rtp:append("/path/to/nvim-laurel")
```
## 🚀 Usage
```fennel
(import-macros {: set! : map! : augroup! : au! ...} :laurel.macros)
```
See [REFERENCE.md](./docs/reference.md) for each macro usage in detail.
### 🔥 Macro List
- [Autocmd](./docs/reference.md#autocmd)
- [`augroup!`](./docs/reference.md#augroup): A replacement of
`vim.api.nvim_create_augroup`
- [`autocmd!`](./docs/reference.md#autocmd-1): A replacement of
`vim.api.nvim_create_autocmd`
- [`au!`](./docs/reference.md#au): An alias of `autocmd!`
- [Keymap](./docs/reference.md#Keymap)
- [`map!`](./docs/reference.md#map): A replacement of `vim.keymap.set`, but
compiles into `vim.api.nvim_set_keymap`.
- [`unmap!`](./docs/reference.md#unmap): A replacement of `vim.keymap.del`,
but compiles into `vim.api.nvim_del_keymap`.
- [``](./docs/reference.md#Cmd)
- [``](./docs/reference.md#C-u)
- [Option](./docs/reference.md#Option)
- [`let!`](./docs/reference.md#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!`](#docs/reference.md#set): A [`let!`][`let!`] alternative dedicated
to handle Vim option value like `vim.opt`.
- [`setglobal!`](#docs/reference.md#setglobal) A [`let!`][`let!`] alternative
dedicated to handle Vim global option value like `vim.opt_global`.
- [`setlocal!`](#docs/reference.md#setlocal) A [`let!`][`let!`] alternative
dedicated to handle Vim local option value like `vim.opt_local`.
- [Variable](./docs/reference.md#Variable)
- [`g!`](./docs/reference.md#g): A [`let!`][`let!`] alternative dedicated to
handle Vim global variable `vim.g`.
- [`b!`](./docs/reference.md#b): A [`let!`][`let!`] alternative dedicated to
handle Vim buffer-local variable `vim.b`.
- [`w!`](./docs/reference.md#w): A [`let!`][`let!`] alternative dedicated to
handle Vim window-local variable `vim.w`.
- [`t!`](./docs/reference.md#t): A [`let!`][`let!`] alternative dedicated to
handle Vim tabpage-local variable `vim.t`.
- [`v!`](./docs/reference.md#v): A [`let!`][`let!`] alternative dedicated to
handle Vim variable `vim.v`.
- [`env!`](./docs/reference.md#env): A [`let!`][`let!`] alternative dedicated
to handle environment variable `vim.env`.
- [Others](./docs/reference.md#Others)
- [`command!`](./docs/reference.md#command): A replacement of
`vim.api.nvim_create_user_command`
- [`feedkeys!`](./docs/reference.md#feedkeys)
- [`highlight!`](./docs/reference.md#highlight)
- [`hi!`](./docs/reference.md#hi)
## 🔄 Alternatives
- [aniseed](https://github.com/Olical/aniseed)
- [hibiscus.nvim](https://github.com/udayvir-singh/hibiscus.nvim)
- [katcros-fnl](https://github.com/katawful/katcros-fnl)
- [nvim-anisole-macros](https://github.com/katawful/nvim-anisole-macros)
- [nyoom.nvim](https://github.com/shaunsingh/nyoom.nvim)
- [themis.nvim](https://github.com/datwaft/themis.nvim)
- [zest.nvim](https://github.com/tsbohc/zest.nvim)
[Fennel]: https://github.com/bakpakin/Fennel
[nvim-thyme]: https://github.com/aileot/nvim-thyme
[hotpot.nvim]: https://github.com/rktjmp/hotpot.nvim
[`let!`]: ./docs/reference.md#let