nvim-hs
Neovim API for Haskell plugins as well as a plugin provider.
This library and executable should provide a basis for developing
plugins. This package should only contain broadly useful interfaces
to write plugins for neovim in haskell. The design goal is to create
an easy to use API that avoids most of the boilerplate while still retaining
some sense of reliability and type safety. Since Template Haskell is used
to generate the neovim bindings and to avoid some of the boilerplate
handy work, some exotic operating systems and architectures may not work.
What do I have to expect if I were to use it now?
Check the issue list here on github.
How do I start using this?
First, you have to decide how you want to manage your plugins. Every section
of this chapter describes an alternative way to manage your plugins. It
starts with a list of pros and cons and then explains what you have to do to
get rolling and how you would install a nvim-hs
-compatible plguin. The
general library documentation is in the haddocks on
(hackage).
If you are new to Haskell development or you don't really care how you manage
your plugins, I (saep) recommend the stack template approach.
Stack via the template
Pros
- Easy to setup because of the template
- Flexible dependency management; everything that stack supports can be done, this
includes packages on stackage, packages on hackage, local packages and repositories
- Reprobucible; if it works once, it will work in the future
- If you don't use stack just for neovim plugins and you have other projects with the
same (or a similiar) lts (long term support) version, you save compilation time on the
initial setup
Cons
- A bit verbose; you have to add dependencies twice if they are not in the stackage snapshot
Installation
First, you must install stack.
You have to have installed neovim and the executable nvim
must be on the path.
(The API code generation calls nvim --api-info
.)
Afterwards, you switch to your neovim configuration folder (typically ~/.config/nvim
) and
you have to create your plugin project.
cd ~/.config/nvim
stack new my-nvim-hs https://raw.githubusercontent.com/neovimhaskell/nvim-hs/master/stack-template.hsfiles --bare --omit-packages --ignore-subdirs
Since nvim-hs
is not yet on stackage, you have to edit the generated
stack.yaml
file by hand (sorry about that). Replace the packages list with
one containing the current directory and the extra-deps list with a
dependency to nvim-hs. The lines of the file that look like this
packages: []
extra-deps: []
should become:
packages:
- .
extra-deps:
- nvim-hs-0.2.0
Now, you have to compile everything.
stack setup
stack build
If there are no errors (there shouldn't be any), you only have to tell neovim how to start this.
Add the following to your init.vim
:
if has('nvim') " This way, you can also put this in your plain vim config
" function which starts a nvim-hs instance with the supplied name
function! s:RequireHaskellHost(name)
" It is important that the current working directory (cwd) is where
" your configuration files are.
return jobstart(['stack', 'exec', 'nvim-hs', a:name.name], {'rpc': v:true, 'cwd': expand('$HOME') . '/.config/nvim'})
endfunction
" Register a plugin host that is started when a haskell file is opened
call remote#host#Register('haskell', "*.l\?hs", function('s:RequireHaskellHost'))
" But if you need it for other files as well, you may just start it
" forcefully by requiring it
let hc=remote#host#Require('haskell')
endif
If you start neovim now, you can use the predefined functions from the template.
:echo NextRandom()
should print a random number.
Installing a plugin from Hackage
Let's take nvim-hs-ghcid
as an example. Since it is not on stackage, have to declare the dependency
in the my-nvim-hs.cabal
file and in the stack.yaml
file. In the .cabal
file, add nvim-hs-ghcid
to the build-depends
section. It should look
like this:
build-depends: base >= 4.7 && < 5
, nvim-hs >= 0.2.0 && < 1.0.0
, nvim-hs-ghcid
You can omit the version number, since you will have to define it in the
stack.yaml
file and you are managing you dependencies with stack anyways.
The extra-deps
section of the stack.yaml
should look like this:
extra-deps:
- nvim-hs-0.2.0
- nvim-hs-contrib-0.2.0
- nvim-hs-ghcid-0.2.0
What is the nvim-hs-contrib
dependency we had to add there? The plugin we
chose to install had a dependency to a haskell project that is not on
stackage. You have to add these to the stack.yaml file as well, although you
do not necessarily have to add them to the cabal file. This is exactly the
disadvantage of using stack for this. The benefit is that you will have a
reproducible build in the future and you don't have to hunt down a working
set of version boundariesfor every dependency you have. A little effort now
will save you more time later!
Note that I (saep) intend to add nvim-hs
and nvim-hs-contrib
to stackage
once I feel I should switch to version 1.0.0. Then, you wouldn't have to
edit the stack.yaml
for this. If you want to update a dependency/plugin,
you have to manually increment the version number in the stack.yaml file and
possibly fix the compilation errors that arise. If you want a rolling
release for a plugin, follow the instructions for installing a plugin from
git.
To use the plugin, add it to the plugins list of the nvim.hs
file in
~/.config/nvim
:
import Neovim
import qualified Neovim.Example.Plugin as Example
import qualified Neovim.Ghcid as Ghcid
main :: IO ()
main = do
neovim defaultConfig
{ plugins = plugins defaultConfig ++
[ Example.plugin
, Ghcid.plugin
]
}
Installing a plugin from git
This method is best suited for plugins that update a lot and for which you need
the most recent version most of the time. If you don't intend to work on the
code of that plugin repository, you can add it to the plugin list of your
plugin manager (e.g. vim-plug).
This way, you get updates if you update all your normal vim plugins.
To stay with the example of the previous section, we use the nvim-hs-ghcid
plugin again.
Add the plugin to your plugin manager (here with vim-plug as an example):
Plug 'saep/nvim-hs-ghcid', { 'for': ['haskell'] }
Once vim-plug has cloned or updated the repository, add the plugin to the
packages list of the stackage.yaml
file. The packages list should look
like this:
packages:
- .
- plugged/nvim-hs-ghcid
As long as you have the repository in this list, you don't have to specify
it as a dependency anywhere else, you still have to add the plugins'
dependencies to the stack.yaml
file, though. It should look like this:
extra-deps:
- nvim-hs-0.2.0
- nvim-hs-contrib-0.2.0
Add the plugin to the plugins list in nvim.hs
in exactly the same way as
described in the previous chapter.
The downside of this is that your compilation times will be longer the more
plugins you include this way.
Writing your own functions that you can call from neovim
The stack template generated a few files for you that you can use as a
template to write your own plugins. If you edit them and make a mistake that
the Haskell compiler can detect, an item in the quickfix list should appear.
This is, unless you removed plugins defaultConfig
from nvim.hs
.
Contributing
Documentation, typo fixes and alike will almost always be merged.
If you want to bring forward new features or convenience libraries
for interacting with neovim, you should create an issue first. The features
of this (cabal) project should be kept small as this helps
reducing the development time. (For some tests it is
necessary to issue cabal install
, so any change to to a module can
significantly increase the compilation time.)
If your idea solves a general problem, feel free to open an issue in the
library project of nvim-hs:
nvim-hs-contrib