Repository files navigation

moonwalk allows you to use any language that compiles to Lua anywhere in yourNeovim configuration.

init.lua:

require("moonwalk").add_loader("fnl",function(src)returnrequire("fennel").compileString(src)end)

fnl/hello.fnl:

(print"Hello world")

Open Neovim and run:lua require("hello").

after/ftplugin/lua.fnl:

(setvim.bo.expandtabtrue)(setvim.bo.shiftwidth17)

Openinit.lua in Neovim and confirm that:set expandtab? showstrue and:set shiftwidth? shows17.

moonwalk inserts a shim into the Lua package loader that transparently compilessource files into Lua. The compilation is cached and will not be repeatedunless the source file changes.

This means that the cost of compilation is only paid once: future invocationswill execute as fast as native Lua.

moonwalk intercepts:source and:runtime commands for files with theextensions you provide. This allows you to use any language anywhere you canuse a.vim or.lua file natively (with a couple of exceptions, seecaveats) such asplugin,ftplugin, orindent files.

The only requirement is a function that can transform a string of the sourcelanguage code into Lua. For example, with Fennel:

require("moonwalk").add_loader("fnl",function(src,path)returnrequire("fennel").compileString(src, {filename=path })end)

The provided function can also take an optional second parameterpath withthe full path of the file being compiled.

Onceadd_loader is called, any files with the extension provided found underaplugin directory on the user's'runtimepath' are sourced. You can alsorequire() files found under any{ext} directories on your'runtimepath',where{ext} is the first argument toadd_loader. For example, if you add aloader for Teal withadd_loader("tl", function(src) ... end) you canrequire() any*.tl files within atl directory on your'runtimepath'(just as you canrequire()*.lua files within alua directory).

This also works withplugin andftplugin files. For example, you canconfigure how Neovim works with C files by creating~/.config/nvim/after/ftplugin/c.fnl with the contents:

(setvim.bo.expandtabfalse)(setvim.bo.shiftwidth8)

The examples above use Fennel, but so long as you can define a function thattransforms the source into Lua, you can use any source language you want,including custom DSLs!

Theadd_loader function takes an optional table as its third argument withthe following keys:

• dir: Directory to use in the'runtimepath' to find modules for thisloader (for example, Lua modules are found under thelua directory). Thedefault is the extension passed as the first argument toadd_loader, e.g.if the file extension is "tl" then script files will be searched for underthetl directory.

• moonwalk is minimal by design: the only thing it provides is the shiminfrastructure. Users must provide their transformation functions themselves(see thewiki for some user-contributed examples).

• The:colorscheme command won't work natively with alternative languages,since it does not go through theSourceCmd autocommand. There are a coupleof ways to get around this:

  1. If you are already using aninit.lua file, you can simply write yourcolorscheme file as a script and thenrequire() it rather than using the:colorscheme command.
  2. If you are using aninit.vim file you can create a stub colorscheme filethatrequire()s your actual colorscheme file. See an examplehere:stub,colors.

It's not, but it's fun.

Short answer: marginal.

Long answer:

Compiling languages into Lua takes a non-trivial amount of time, but this isonly done once so you shouldn't worry about it. Once the source file iscompiled it is cached until the source file changes again. Future invocationsare (nearly) as fast as using Lua directly.

It is onlynearly as fast because the custom loader that moonwalk inserts isat the end of Lua'spackage.loaders table. This means that when yourequire() a module written in an extension language Lua has to iteratethrough the other package loaders first before it finally gets to moonwalk.moonwalk also has to do a few things in order to determine whether or not thesource file has changed such as checking file modification times. However, thisprocess takes on the order of microseconds, so don't sweat it too much.

The other performance impact comes from searching for runtime files in thegiven extension language. On startup, moonwalk runs (essentially) the followingcommand:

:runtime!plugin/**/*.{ext}

where{ext} is the provided extension (e.g.moon,tl, etc.). Searchingthrough the runtime path recursively takes a few milliseconds, so if you are astartuptime junkie you may notice this. moonwalk takes measures to speed upthis process as much as possible, but there is a ceiling on how fast this canbe done.

• moonwalk is heavily inspired byhotpot.nvim. Hotpot works only withFennel but provides far more features than moonwalk.
• aniseed is another plugin that provides Fennel support for Neovim, alongwith an entire standard library and utility functions.

If you extend Neovim with an extension language other than Fennel, please letme know so I can include some of those entries in theexamples.

The wiki is publicy editable. If you think you have a useful contribution,please share it!

File issues in theGitHub issue tracker. Changes can be sent asgit-send-email patches to~gpanders/public-inbox@lists.sr.ht or as a GitHub pull request.

GPLv3