nvim-hs: Haskell plugin backend for neovim

[ apache, editor, library ] [ Propose Tags ]

This package provides a plugin provider for neovim. It allows you to write plugins for one of the great editors of our time in the best programming language of our time! ;-) . You should find all the documentation you need inside the Neovim module. Most other modules are considered internal, so don't be annoyed if using things from there may break your code! . The following modules may also be of interest and they should not change their API: Neovim.Quickfix . If you want to write unit tests that interact with neovim, Neovim.Test provides some useful functions for that. . If you are keen to debug nvim-hs or a module you are writing, take a look at the Neovim.Debug module. . If you spot any errors or if you have great ideas, feel free to open an issue on github.


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.0.1, 0.0.2, 0.0.3, 0.0.5, 0.0.6, 0.0.7, 0.0.8, 0.1.0, 0.2.0, 0.2.1, 0.2.2, 0.2.3, 0.2.4, 0.2.5, 1.0.0.0, 1.0.0.1, 1.0.0.2, 1.0.0.3, 2.0.0.0, 2.1.0.0, 2.1.0.2, 2.1.0.3, 2.1.0.4, 2.1.0.5, 2.1.0.7, 2.2.0.0, 2.2.0.1, 2.2.0.2, 2.2.0.3, 2.3.0.0, 2.3.1.0, 2.3.2.0, 2.3.2.1, 2.3.2.3 (info)
Change log CHANGELOG.md
Dependencies base (>=4.9 && <5), bytestring, cereal, cereal-conduit (>=0.8.0), conduit (>=1.3.0), containers, data-default, deepseq (>=1.1 && <1.6), foreign-store, hslogger, megaparsec (<10), messagepack (>=0.5.4), mtl (>=2.2.1 && <2.4), network, optparse-applicative, prettyprinter, prettyprinter-ansi-terminal, streaming-commons, template-haskell, template-haskell-compat-v0208 (>=0.1.9), text, time, time-locale-compat, typed-process, unliftio (>=0.2), unliftio-core (>=0.2), utf8-string, vector, void [details]
License Apache-2.0
Copyright Copyright 2017-2022 Sebastian Witte <woozletoff@gmail.com>
Author Sebastian Witte
Maintainer woozletoff@gmail.com
Revised Revision 1 made by saep at 2023-12-27T12:47:18Z
Category Editor
Home page https://github.com/neovimhaskell/nvim-hs
Source repo head: git clone https://github.com/neovimhaskell/nvim-hs
Uploaded by saep at 2023-06-17T12:50:29Z
Distributions LTSHaskell:2.3.2.3, NixOS:2.3.2.3, Stackage:2.3.2.3
Reverse Dependencies 6 direct, 1 indirect [details]
Downloads 11837 total (62 in the last 30 days)
Rating 2.5 (votes: 6) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-06-17 [all 1 reports]

Readme for nvim-hs-2.3.2.3

[back to package description]

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.

Hackage version nvim-hs on latest Stackage LTS nvim-hs on Stackage Nightly

What do I have to expect if I were to use it now?

Check the issue list here on github.

For Windows users

Named pipes are not supported at the momend #103. You therefore have to start nvim-hs instances by connecting to STDIN and STDOUT or TCP. By default nvim-hs connects to the listen socket pointed to by the NVIM environment variable and the functions in the module Neovim.Debug rely on that. If you want to be able to run these functions, start Neovim with nvim --listen localhost: or similar (This example command starts neovim with a socket listening on localhost and random a random TCP port.)

How do I start using this?

You need to install nvim-hs.vim, a plugin that manages starting of nvim-hs plugins. To do that, just follow the instructions outlined here.

Once you have installed nvim-hs.vim, you can use nvim-hs plugins as you would normal vim plugins. Note that every plugin you install is started as a separate process, which should be fine unless you have a lot of them.

Scripting with Haskell

The entry point for all Haskell-based scripts is a plugin. An nvim-hs plugin is a plain Haskell project with two conventions:

  1. You need an executable that starts a msgpack-rpc compatible client.

  2. You need a tiny bit of vimL in your runtime path that starts the plugin.

The simplest way to get started is using the stack template from this repository/package inside your Neovim configuration folder, but you can also manually create a project by doing everything that is explained in :help nvim-hs.txt (which should be available if you installed nvim-hs.vim as mentioned in the previous section).

To use that template, you'll first need to install stack and have the Neovim executable on the path (the API code generation calls nvim --api-info so it needs access to nvim).

After you've done that, you can run these commands to setup the template (assuming your Neovim configuration folder is in $XDG_CONFIG_HOME/nvim):

$ cd $XDG_CONFIG_HOME/nvim
$ stack new my-nvim-hs \
https://raw.githubusercontent.com/neovimhaskell/nvim-hs/master/stack-template.hsfiles \
--bare --omit-packages --ignore-subdirs

If you start Neovim now, it will compile the example plugins which may take a few minutes. Once it is started you can use the predefined functions from the template, for example by running :echo NextRandom(), which should print a random number.

To start writing your own functions and plugins, read through the files generated by the template and also check out the library documentation on hackage.

Contributing

Documentation, typo fixes, and the like 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 reduce 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.