neovim/lua-client

DEPRECATED

Documentation | Chat

Neovim is a project that seeks to aggressively refactor Vim in order to:

• Simplify maintenance and encourage contributions
• Split the work between multiple developers
• Enable advanced UIs without modifications to the core
• Maximize extensibility

See the Introduction wiki page and Roadmap for more information.

Features

• Modern GUIs
• API access from any language including C/C++, C#, Clojure, D, Elixir, Go, Haskell, Java/Kotlin, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, Ruby, Rust
• Embedded, scriptable terminal emulator
• Asynchronous job control
• Shared data (shada) among multiple editor instances
• XDG base directories support
• Compatible with most Vim plugins, including Ruby and Python plugins

See :help nvim-features for the full list, and :help news for noteworthy changes in the latest version!

Install from package

Pre-built packages for Windows, macOS, and Linux are found on the Releases page.

Managed packages are in Homebrew, Debian, Ubuntu, Fedora, Arch Linux, Void Linux, Gentoo, and more!

Install from source

See BUILD.md and supported platforms for details.

The build is CMake-based, but a Makefile is provided as a convenience. After installing the dependencies, run the following command.

make CMAKE_BUILD_TYPE=RelWithDebInfo
sudo make install

To install to a non-default location:

make CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_INSTALL_PREFIX=/full/path/
make install

CMake hints for inspecting the build:

• cmake --build build --target help lists all build targets.
• build/CMakeCache.txt (or cmake -LAH build/) contains the resolved values of all CMake variables.
• build/compile_commands.json shows the full compiler invocations for each translation unit.

Transitioning from Vim

See :help nvim-from-vim for instructions.

Project layout

├─ cmake/           CMake utils
├─ cmake.config/    CMake defines
├─ cmake.deps/      subproject to fetch and build dependencies (optional)
├─ runtime/         plugins and docs
├─ src/nvim/        application source code (see src/nvim/README.md)
│  ├─ api/          API subsystem
│  ├─ eval/         Vimscript subsystem
│  ├─ event/        event-loop subsystem
│  ├─ generators/   code generation (pre-compilation)
│  ├─ lib/          generic data structures
│  ├─ lua/          Lua subsystem
│  ├─ msgpack_rpc/  RPC subsystem
│  ├─ os/           low-level platform code
│  └─ tui/          built-in UI
└─ test/            tests (see test/README.md)

License

Neovim contributions since b17d96 are licensed under the Apache 2.0 license, except for contributions copied from Vim (identified by the vim-patch token). See LICENSE for details.

Vim is Charityware.  You can use and copy it as much as you like, but you are
encouraged to make a donation for needy children in Uganda.  Please see the
kcc section of the vim docs or visit the ICCF web site, available at these URLs:

        https://iccf-holland.org/
        https://www.vim.org/iccf/
        https://www.iccf.nl/

You can also sponsor the development of Vim.  Vim sponsors can vote for
features.  The money goes to Uganda anyway.

lua-client's Issues

Adding documentation to the README

Hi – this library is missing useful beginner documentation that I've had to derive from trawling through test cases and source code.

There was a request for docs in #22 5 years ago, but it was closed as "the library is not sufficient for end users".

There was also a request for docs in #33 3 years ago, but it was closed as "this is used by all 3500+ tests in nvim", e.g. "just read the tests".

I think it's time for some introductory documentation, and I'm happy to write up what I've discovered so far, if you're willing to accept patches. I think at this point, if there are 3500 tests using this library, there exists at least some semblance of a stable API that is worth at least giving some introductory text on. If the API is not stable, you'll end up rewriting 3500+ tests in Neovim, so I just don't see it breaking so hard that documentation should be kept close to the vest.

What do you think? I'm happy to contribute to the docs as the first step.

Please use the HTTP(S) repo url in the rockspec file

Many people behind corporate firewalls cannot connect to the outside world via SSH (git://), so it would be much appreciated if you could update the rockspec file to change the source URL to https://github.com/neovim/lua-client.git (or possibly just http, until luarocks support for HTTPS is widespread).

publish new release

@teto can you push the latest version to https://luarocks.org/modules/teto/nvim-client ? Your account on luarocks owns the "root" listing for nvim-client.

A thought

I've been following neovim and saw the lua-client... I work on the luvit project, and we've created a new project called Luvi [1]. It might fit the bill nicely for a framework for lua plugins:

https://github.com/luvit/luvi

how can I install?

How can I install this client?

Document usage

Hiya

Are there docs for this client anywhere?

Thanks,
Louis

"Session using SocketStream throws ENOENT" test fails with libuv 1.20.3

Debian's CI infrastructured discovered that this test started failing when libuv was upgraded to 1.20.3 (from 1.18.0):

[ RUN      ] test/session_spec.lua @ 180: Session using SocketStream throws ENOENT error when socket does not exist
test/session_spec.lua:181: Expected a different error.
Caught:
(no error)
Expected:
(string) 'ENOENT'

While this is clearly a behavior change, I'm not sure if it's a regression in libuv or if we were relying on something that we shouldn't have been.

Any insight would be helpful to get this resolved.

I have limited time for the next ~week. I was going to try bisecting libuv, but between the annoying lua-client build (when you don't want bundled deps) and the fact that libuv is pulled in through lua-luv, I won't have time to do that soon.

tests: failure with copied session_spec

I've noticed that this fails: cp -a test/session{,_new}_spec.lua; make test:

[----------] 24 tests from test/session_new_spec.lua (1645.26 ms total)

[----------] Running tests from test/session_spec.lua
./nvim/msgpack_rpc_stream.lua:1: attempt to index a userdata value

stack traceback:
        ./nvim/msgpack_rpc_stream.lua:1: in main chunk

[----------] 0 tests from test/session_spec.lua (2.01 ms total)

[----------] Global test environment teardown.
[==========] 24 tests from 2 test files ran. (1647.72 ms total)
[  PASSED  ] 24 tests.
[  ERROR   ] 1 error, listed below:
[  ERROR   ] ./nvim/msgpack_rpc_stream.lua @ 1: suite test/session_spec.lua

 1 ERROR
make: *** [Makefile:48: test] Error 1

I.e. when the same spec file is loaded again the local mpack = require('mpack') there fails:

lua-client/nvim/msgpack_rpc_stream.lua

Line 1 in af24091

local mpack = require('mpack')

It's not clear to me what's causing this - it might indicate some inconsistent global state?

How use this API?

Can you put any documentation about how use this lua API?
Where are existing plugins using this APIs?

That still doesn't be for end-users? #22

Client does not work with nil properly

When writing Neovim tests try using helpers.meths.set_var('name', nil). This will error out, complaining about wrong number of arguments. I have checked the code and it appears that all helper methods written here pass arguments unchanged (i.e. use func({some args}, ...) (... means literal ... here)) and not something like {...} (which in case argument is nil will produce {nil} which is {[1]=nil} which is {} because tables cannot hold nil values).

Easiest fix there will be creating special exported table named nil_tbl and overriding msgpack dumper to dump this table as nil, this will also fix problem with nil that cannot possibly appear inside tables and not just inside other values.

Future/Status

From the readme: https://github.com/neovim/lua-client#future-plans

The future of lua-client (this repo) is grim, because the future of Nvim Lua is supple and verdant:

1. Nvim core will gain the ability to run Lua code via nvim -l.
2. We will include some sort of Lua client in Nvim core. Perhaps starting with https://github.com/justinmk/lua-client2
3. Legacy lua-client (this repo) will be archived.

The goal is for Nvim to be able to spawn child nvim processes and then they can be clients of each other using a builtin Lua client which uses Nvim's builtin Lua and msgpack + msgpack-RPC stuff.