Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Olical/aniseed

Neovim configuration and plugins in Fennel (Lisp compiled to Lua)
https://github.com/Olical/aniseed

fennel lisp lua neovim

Last synced: 14 days ago
JSON representation

Neovim configuration and plugins in Fennel (Lisp compiled to Lua)

Awesome Lists containing this project

README 

        
= Aniseed https://discord.gg/wXAMr8F[image:https://img.shields.io/discord/732957595249410108.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2[Discord]]



Aniseed bridges the gap between https://fennel-lang.org/[Fennel] (a Lisp that compiles to Lua) and https://neovim.io/[Neovim]. Allowing you to easily write plugins or configuration in a https://clojure.org/[Clojure]-like Lisp with great runtime performance.



____

Note: You may be interested in my new project that attempts to be a successor to Aniseed, https://github.com/Olical/nfnl[nfnl].



It does away with a bunch of decisions I regretted and builds upon the parts I really liked. I think you might like it too!



Future development efforts will center around nfnl instead of Aniseed and things like Conjure will almost certainly transition over to being based on it instead over time.

____



https://asciinema.org/a/326401[image:https://asciinema.org/a/326401.svg[asciicast]]



Further documentation can be found in link:doc/aniseed.txt[`:help aniseed`]. There you can learn about the scripts, macros, functions and use cases of Aniseed.



== Installation



For interactive evaluation you need to install https://github.com/Olical/conjure[Conjure] as well. It'll allow you to send portions of your code off for evaluation as well as see the results in an interactive log buffer. You may also use the, far more minimal, `:AniseedEval {code}` and `:AniseedEvalFile {path}` commands to execute Fennel if you require.



You may be interested in https://github.com/Olical/nvim-local-fennel[nvim-local-fennel] which is essentially a Fennel based version of https://github.com/embear/vim-localvimrc[localvimrc].



Alternatively you can use https://github.com/Olical/magic-kit[Magic Kit], an opinionated starter kit that includes all sorts of essential tools.



=== https://github.com/wbthomason/packer.nvim[packer.nvim]



[source,lua]

----

use 'Olical/aniseed'

----



=== https://github.com/junegunn/vim-plug[vim-plug]



[source,viml]

----

Plug 'Olical/aniseed'

----



== Module macros



Aniseed ships with a set of module macros that make interactive evaluation not only possible, but rich and intuitive. You should read `:h aniseed` to learn the details but it's worth mentioning that you opt in by starting your file with a `(module ...)` block, you then export values from your module with the `(def...)` macros.



Once you opt in your module will no longer operate like a regular Fennel module in the sense that you can't just return a table from the bottom of your file to export it like so.



```fennel

(local somemod {})

(set somemod.foo 25)

somemod

```



In vanilla Fennel, this will build and return a table from your module. If you use Aniseed's macro system your file must look like this instead.



```fennel

(module somemod)

(def foo 25)

```



== Loading Fennel Neovim configuration



Aniseed has a module called `aniseed.env` which will automatically compile and load Fennel code from your Neovim configuration directory as if it were natively supported by the editor, like Lua and VimL.



See https://github.com/Olical/dotfiles/tree/a950167446c656a6ba10ddf7400072cd0107c24c/stowed/.config/nvim/fnl[Olical/dotfiles] for a detailed example configuration. To enable this same automatic loading of your Fennel configuration you need to install Aniseed and add the following option. This is documented further within `:help aniseed`.



[source,viml]

----

let g:aniseed#env = v:true

----



Now the following code in `~/.config/nvim/fnl/init.fnl` will be compiled and executed when you open Neovim.



[source,clojure]

----

;; The name is up to you.

(module nvim-config

  {;; You can use Lua's regular require or Aniseed's autoload.

   require {xyz some.cool.tool.xyz



            ;; Fennel destructuring syntax works but defeats the point of autoload.

            ;; Because a lookup is instantly invoked which triggers autoload at

            ;; module load time instead of when you need it in your code.

            {: some-fn} some-module}



   ;; Autoload lazily loads the module when you try to use the module methods or values at runtime.

   autoload {a aniseed.core



             ;; Shorthand syntax for requiring under the same name.

             : packer}})



(a.println "Hello, World!")

----



== Setting up a plugin project



`scripts/seed.sh` is provided to make it a little easier to get a plugin up and running. In a new directory (because it will overwrite your `.gitignore` and `Makefile` etc) run the following command.



It will name the plugin after the directory you're currently running it from. Make sure the directory name doesn't include any spaces or special characters because it will be inserted at some points in the seed code for you.



[source,bash]

----

curl -fL https://raw.githubusercontent.com/Olical/aniseed/master/scripts/seed.sh | sh

----



This will create some example Fennel source and tests as well as a `Makefile` to help you compile and run it all. This should be enough to get you started without being overly opinionated.



== Unlicenced



The following files are excluded from my license and ownership:



 * `lua/aniseed/deps/fennel.lua`

 * `lua/aniseed/deps/nvim.lua`



These files come from https://fennel-lang.org/[Fennel] and https://github.com/norcalli/nvim.lua[nvim.lua], *I did not write them*, all other files are from me and unlicenced. The aforementioned files should be considered under their respective project licences. They are copied into this repo to allow the plugin to work with systems that don't support symlinks correctly.



Find the full http://unlicense.org/[unlicense] in the `UNLICENSE` file, but here's a snippet.



____

This is free and unencumbered software released into the public domain.



Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

____