Skip to content
ShougoPublic

About

Go based dark powered framework for Vim/Neovim

Topics

Resources

Stars

40 stars

Watchers

1 watching

Forks

Latest commit

 

History

53 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

goda.vim

Go based dark powered framework for Vim/Neovim. (Pronounced "Godda".)

A successor in spirit to denops.vim that does not depend on Deno. A plugin is a Go program; the editor starts it and talks to it. The same binary serves Vim and Neovim.

goda.vim itself knows nothing about completion or any other feature: it moves messages between the editor and plugins, and lets a plugin call back into the editor. Plugins built on it, such as goda-cmp.vim, define their own extension kinds (sources, filters, UIs) as plain Go packages that are linked into the binary at build time.

Status: early. The API may still change; see Status.

Naming

what example notes
framework goda.vim this repository
a Vim plugin built on goda goda-cmp.vim has .vim
an extension goda-cmp-source-file a Go module, no .vim

Do not name a plugin binary goda: go install github.com/loov/goda@latest (an unrelated tool) installs that name.

Install

Install goda.vim with a plugin manager. goda-pm.vim, the plugin manager on goda.vim (the successor of dpp.vim), is the recommended one: its TOML files are those of dpp.vim.

[[plugins]]
repo = 'Shougo/goda.vim'

[[plugins]]
repo = 'Shougo/goda-fi.vim'
depends = 'goda.vim'
# Loaded by the first call of a goda_fi#...() function.
lazy = true

goda.vim itself has no plugin/ script: it is loaded by the first call of a goda#...() function, so it costs nothing at startup. With goda-pm.vim, do not make it lazy (goda-pm.vim uses it to make its state and to install the plugins).

Try it

This builds and calls a plugin of ten lines. You need Go 1.26 or newer and Vim 9.1 or newer (with +job and +channel) or Neovim 0.11 or newer.

mkdir hello && cd hello
go mod init hello

Save this as main.go:

package main

import (
	"context"
	"fmt"

	"github.com/Shougo/goda.vim/host"
	"github.com/Shougo/goda.vim/sdk"
)

type hello struct{}

func (hello) Name() string { return "hello" }

func (hello) Handlers() map[string]sdk.Handler {
	return map[string]sdk.Handler{
		"greet": func(ctx context.Context, h sdk.Host, params []any) (any, error) {
			// The arguments: a string (an error otherwise).
			var name string
			if err := sdk.DecodeArgs(params, &name); err != nil {
				return nil, err
			}
			// Ask the editor for something: its current working directory.
			cwd, err := h.Call(ctx, "getcwd")
			if err != nil {
				return nil, err
			}
			return fmt.Sprintf("hello, %s, from %s (cwd %v)", name, h.Meta().Host, cwd), nil
		},
	}
}

func main() { host.Main(hello{}) }

Build it:

go get github.com/Shougo/goda.vim@latest
go mod tidy
go build -o hello .

Then, in Vim or Neovim (adjust the paths):

set runtimepath+=/path/to/goda.vim
call goda#start('/path/to/hello/hello')
echo goda#request('hello', 'greet', 'world')
" hello, world, from vim (cwd /home/you)      (from nvim in Neovim)

A plugin need not start its binary itself: goda#register() says how, and the first request starts it (and starts it again after it stopped):

" autoload/hello.vim: read with the first call of a hello#...() function
call goda#register('hello', '/path/to/hello/hello')  " or a Funcref

function! hello#greet(name) abort
  return goda#request('hello', 'greet', a:name)
endfunction

If something goes wrong, echo goda#log() shows what the binary wrote to stderr.

Without an editor, the development transport answers one JSON request per line. Calls into the editor (like getcwd above) fail in this mode, but everything else can be exercised:

echo '{"method":"goda.plugins"}' | ./hello --transport=jsonl
# {"result":{"hello":["greet"]}}

Documentation

:help goda (doc/goda.txt): the Vim script functions and variables, writing a plugin (the sdk interfaces, sdk.Closer), and versions and the handshake.

How it works

Neovim ── msgpack-rpc over stdio ─┐
                                  ▼
Vim ───── JSON channel over stdio ─► plugin binary ── your plugins and their
                                     (one process       extensions, linked in
                                      per binary)       as ordinary Go packages

Extensions are not loaded at run time; they are Go packages imported by the plugin's own main, so versions are pinned by go.mod and the compiler checks the whole program. Building needs Go; running does not. Pure Go, no cgo.

directory
autoload/goda.vim the Vim script side, for both editors
sdk/ the contract plugins are written against
host/ host.Main and the transports nvim/, vim/, jsonl/
internal/ the msgpack codec and JSON helpers

Tests

go test ./...        # includes real editors: Vim (+job +channel) and Neovim, if installed
go test -short ./... # without starting an editor

host/e2e runs one scenario through autoload/goda.vim in every editor it finds; CI (.github/workflows/ci.yml) installs both.

AI-assisted, not AI-dependent

AI is used as a tool to speed up development, but goda.vim and the plugins in this project are not built on the assumption that AI exists.

Status

Checked: go vet, go test (and -race), both transports and the Vim script against Vim 9.1 and Neovim 0.12 on Linux, several binaries at once, the handshake. Not checked by the automated tests: Windows, macOS.

License

MIT, see LICENSE.

About

Go based dark powered framework for Vim/Neovim

Topics

Resources

Stars

40 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages