failwind.nvim - Introduction

# `failwind.nvim` It all started here... ![[Pasted image 20240806165512.png|500]] When I hear someone say "configuration", I immediately start salivating like Pavlov getting excited to ring the bell. I thought to myself > Surely I can make Neovim's primary configuration language be CSS > [!NOTE] > I want to mention that I only asked whether I could do this thing, not whether I should. Something my twitch chat reminded me of regularly # Configuration Let's start with the simplest configuration we can specify using `failwind`: Neovim options. ## Configuration: Options ```neovim {"update":true,"path":"_/code/1722978571694.css","timestamp":1725472708323} <pre> options { number: true; relativenumber: false; /* ... other options ... */ shiftwidth: 4; /* Language specific options */ css { expandtab: true; shiftwidth: 2; tabstop: 2; } javascript, typescript { tabstop: 2; } } </pre> ``` ^1722978571694 Neovim options are configured by including a `tag selector` or `options`, and then providing a key-value pairing of options and values. Rich option types are accepted, not just strings. So you can pass numbers, strings, booleans, and lists. Furthermore, you can specify filetype specific options using nested `tag selectors` - even passing multiple `tag selectors` as a list to configure multiple filetypes at once! ## Configuration: Keymaps Of course, basic configuration wouldn't be complete without being able to specify keymaps! One of the nice things about turning CSS into a DSL is that I can do anything I want with it! For example, we have a different ways of specifying what happens on the right-hand side of a keymap. ```neovim {"update":true,"path":"_/code/1722999600204.css","timestamp":1725472708075} <pre> /* Top-level keymaps container */ keymaps { normal { :key("<esc>") { command: "nohlsearch"; } :key("<leader>q") { action: lua("vim.diagnostic.setloclist()"); } } terminal { :key("<esc><esc>") { action: "<C-\><C-n>"; desc: "wow, escape terminal mode"; } } } </pre> ``` ^1722999600204 The first item you'll see is using the `command` property. This turns any string into a `<cmd>{command}<CR>` mapping - which is to say something you'd run as an ex-command. ```neovim {"update":true,"path":"_/code/1722999742398.css","timestamp":1725472707846} <pre> :key("<esc>") { command: "nohlsearch"; } </pre> ``` ^1722999742398 In our example of `<esc>`, this is the same as writing: ``` -- vimscript nnoremap <esc> <cmd>nohlsearch<cr> -- lua vim.keymap.set("n", "<esc>", "<cmd>nohlsearch<cr>") ``` So I actually think it looks pretty nice the way we describe it in CSS! I'm still playing around with some other options for specifying the key (it's generally a bit difficult to do because keymaps can have arbitrary characters, which don't play well with CSS identifiers). ```neovim {"update":true,"path":"_/code/1722999867231.css","timestamp":1725472707614} <pre> :key("<leader>q") { action: lua("vim.diagnostic.setloclist()"); } </pre> ``` ^1722999867231 Beyond just specifying an ex-command, we can also specify an `action`, which will be placed directly inside of a `function` that is created for the keymap. The above code is equivalent to: ```neovim {"update":true,"path":"_/code/1722999911679.lua","timestamp":1725472707388} <pre> vim.keymap.set("n", "<leader>q", function() vim.diagnostic.setqflist() end) </pre> ``` ^1722999911679 I think this one is probably just objectively worse because we lose all of our LSP support for this, but it's still cool that we can embed the Lua code directly into the CSS and then call it later from within Neovim. Lastly, if the action is just a string, then we place that on the right-hand side of the mapping, like below: ```neovim {"update":true,"path":"_/code/1722999986048.css","timestamp":1725472707159} <pre> terminal { :key("<esc><esc>") { action: "<C-\><C-n>"; desc: "wow, escape terminal mode"; } } </pre> ``` ^1722999986048 This just directly maps `<esc><esc>` in terminal mode to the sequence of characters used to escape terminal mode (a pretty convenient mapping!). Of course, we support adding descriptions to mappings as well. ## Configuration: Plugins I think this is too long for the first post, so let me know if you want to read a more in-depth item about this by commenting on this article. I'm happy to write something up if people find this interesting and got this far in the post. The teaser looks something like this: ```neovim {"update":true,"path":"_/code/1723000097577.css","timestamp":1725472706926} <pre> plugins { /* Plugin, with default setup configuration */ :repo("echasnovski/mini.nvim") { setup: "mini.trailspace" "mini.ai"; } /* Plugin, with custom setup configuration */ :repo("lewis6991/gitsigns.nvim") { :setup("gitsigns") { signs { add { text: '+' } change { text: '~' } delete { text: '_' } topdelete { text: '‾' } changedelete { text: '~' } } } } :repo("nvim-telescope/telescope.nvim") { depends: "nvim-lua/plenary.nvim"; setup: 'telescope'; keymaps { normal { :key(' sh') { command: "Telescope help_tags"; } /* ... */ :key(' ') { command: "Telescope buffers"; } :key(' sn') { desc: "Search Neovim Files"; @call require('telescope.builtin').find_files { prompt_title: "Search Neovim DotFiles"; cwd: vim-fn-stdpath("config"); } } } } } :repo("neovim/nvim-lspconfig") { depends: "williamboman/mason.nvim" "williamboman/mason-lspconfig.nvim" "WhoIsSethDaniel/mason-tool-installer.nvim"; setup: "mason" "mason-lspconfig"; :setup("mason-tool-installer") { automatic_installation: true; ensure_installed: ["lua_ls", "gopls"]; } :config { @call require('mason-lspconfig').setup_handlers { lua_ls: lua('require("lspconfig").lua_ls.setup {}'); gopls: lua('require("lspconfig").gopls.setup {}'); } } } } </pre> ``` ^1723000097577 In this configuration we setup a few simple plugins, but also get far enough to start attaching LSPs to Lua and Go (and setup auto-installation as well!). Of course we have telescope working, but I removed a few of the keymaps for brevity. ## Configuration: Evaluation Once you have your configuration in some `css` file, it can be loaded by doing: ```neovim {"update":true,"path":"_/code/1723000261387.lua","timestamp":1725472706710} <pre> local css_file = "/path/to/file.css" require("failwind").evaluate(css_file) </pre> ``` ^1723000261387 That's it! `failwind` will load and evaluate the file, install any necessary plugins and then setup them up based on your configuration. It actually works surprisingly well so far. I am still playing quite a bit with some ideas about how we're going to do some of the more complicated configuration items, importing other configurations and more. I have been having an absolute blast goofing around with this idea on stream lately. # Implementation Very short summary of the implementation is that I use `tree-sitter` and the CSS parser to walk the tree and effectively have a tree-walking interpreter written in Lua that executes Lua based on the nodes we hit in the AST. If you're interested in a more detailed write-up for this, let me know. It's not all done, so this part is a bit more in flux anyway. Thanks for reading :) # Acknowledgements Thanks [@jarredsumner](https://x.com/jarredsumner) for this terrible idea! It has been a blast making [this idea](https://x.com/jarredsumner/status/1817174551022969042) happen.