A Basic LSP Server Scaffold Written in Rust
TL;DR
I built a quick-start LSP server1 example. It uses code from rust_analyzer3 for basic plumbing. All you have to do is add functions for your features.
This post is the story. Check out this page for the code: Rust Analyzer LSP Example
MonoColorCode
I've been using Neopolitan4 (the file format) and Neopoligen5 (the website builder) for a couple years. The tool set includes a basic Tree-sitter6 plugin for Neopolitan. It provides highlighting and the ability to execute inline code7. Super handy, even if it's a bit hacky8.
Neopoligen's output is based on templates. They're pretty much naked. No syntax highlighting, linting, or auto-formatting.
I can work with them alright. There's certainly friction. I've use them enough that I don't notice it that much anymore.
That said, if it wasn't my project, I wouldn't deal with it.
Towards An LSP
I'm continuing the march to introduce more folks to Neopoligen. The current work is separating the parser and the website builder. When that's done, I'll start actively promoting the project.
If I was on the other side of that conversation, I'd pass purely from the lack of syntax highlighting. Something so integrated, it's practically invisible. Until it's not there. At which point, it's lack is glaring.
That's where an LSP comes in. A single, purpose-built tool that can serve VS Code, Neovim, or any other capable app the data it needs to highlight, lint, and format.
Protocoling
I found a tutorial and made a prototype LSP server using tower_lsp9. It works. But, the crate10 isn't maintained.
I got turned on to the fact that rust_analyzer has it's own LSP. I jumped over to look at it.
There's a single, minimal example in the repo. It shows how to respond to a gotoDefinition request. While it's not much, it's enough to get started.
State Of The Content Address
The two biggest things I'm after in my LSP are syntax highlighting and auto-formatting. Both require an LSP server to store its own copy of the file11. Something the example doesn't show how to do.
Luckily, the rest of the rust_analyzer code is right there with the example. I was able to yoink a few sections, tweak them a bit, and drop them into my project to get things working.
My confidence in the code is high. Much higher than if I'd come up with a solution on my own.
Grimoire_SP
I rarely jump directly into building a project with something completely new to me. I make little prototypes in my grimoire12 first.
That's what I did with the LSP. A new entry called "rust_analyzer_lsp_example". The write-up will end up on this site at some point. For now, it and the code are here:
A New Example
I also created a ticket in the rust_analyzer asking if they'd like me to copy a version into their examples.
I doubt it would get much use. It would save a few hours for anyone who wanted to get started, though.
Either way, I'm set up for the next step of building the LSP for real13. It's gonna be so nice to get back to having highlighting and formatting.
-a
Endnotes
Neopoligen's templating system is built on MiniJinja with a tweak to the delimiter tokens. Out of the box, MiniJinja uses:
{% blocks %}
{{ variables }}
{# comments #}Those combinations are visually noisier than I'd like. They're also hard for me to track without syntax highlighting.
I changed them up for Neopoligen templates:
[! blocks !] [@ variables @] [# comments #]
The sharp edges of the square brackets are easier for me pick out.
There are some formatters/highlighters that work with the default tokens. I've played around with them but trying to convert them to using the style I prefer would have been lots of work.
They also use Regular Expressions for the parsing. That's way harder to work with than Parser Combinators like nom which is what I use.
Footnotes
Basically, a way to make a little app/server that provides syntax highlighting2, auto-formatting, and more to code editors
Syntax Highlighting is adding colors to computer code in text editors. For example, this:
...becomes this when syntax highlighting is applied
An LSP built for the Rust programming language.
The first tool I used to do syntax highlighting. It's very cool. LSPs have more adoption though. Hence the switch.
Basically, I can have little snippets of code in my notes that run and output their results directly back into the note itself.
The code isn't as generic as I'd like. I have to change it when I add things and it doesn't always highlight things properly. It's good enough for personal use though.
The first thing I used. Worked fine, but I'm wary of using unmaintained code.
A Rust crate is basically a little, pre-built chunk of code that offers some functionality. Using one in your project give you access to the functionality.
The individual requests an editor makes to an LSP server don't include the contents of the file itself. That's an explicit design choice aimed at keeping things a stream-lined as possible.
You could call it a notes app. I call it a book of magic.
I'll make the LSP it's own package that can used either by itself or rolled into Neopoligen. That way folks can just have the single install and get the LSP features built in