plugin

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 18, 2022 License: Apache-2.0 Imports: 11 Imported by: 25

Documentation

Overview

Package plugin is a Nvim remote plugin host.

Example

This plugin adds the Hello function to Nvim.

package main

import (
	"strings"

	"github.com/neovim/go-client/nvim/plugin"
)

func main() {
	plugin.Main(func(p *plugin.Plugin) error {
		p.HandleFunction(&plugin.FunctionOptions{Name: "Hello"}, func(args []string) (string, error) {
			return "Hello, " + strings.Join(args, " "), nil
		})
		return nil
	})
}
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Main

func Main(registerHandlers func(p *Plugin) error)

Main implements the main function for a Nvim remote plugin.

Plugin applications call the Main function to run the plugin. The Main function creates a Nvim client, calls the supplied function to register handlers with the plugin and then runs the server loop to handle requests from Nvim.

Applications should use the default logger in the standard log package to write to Nvim's log.

Run the plugin application with the command line option --manifest=hostName to print the plugin manifest to stdout. Add the manifest manually to a Vimscript file. The :UpdateRemotePlugins command is not supported at this time.

If the --manifest=host command line flag is specified, then Main prints the plugin manifest to stdout insead of running the application as a plugin. If the --location=vimfile command line flag is specified, then plugin manifest will be automatically written to .vim file.

Types

type AutocmdOptions

type AutocmdOptions struct {
	// Event is the event name.
	Event string

	// Group specifies the autocmd group.
	Group string

	// Pattern specifies an autocmd pattern.
	//
	//  :help autocmd-patterns
	Pattern string

	// Nested allows nested autocmds.
	//
	//  :help autocmd-nested
	Nested bool

	// Eval is evaluated in Nvim and the result is passed the the handler
	// function.
	Eval string
}

AutocmdOptions specifies autocmd options.

type CommandOptions

type CommandOptions struct {
	// Name is the name of the command in Nvim. The name must be made of
	// alphanumeric characters and '_', and must start with a capital
	// letter.
	Name string

	// NArgs specifies the number command arguments.
	//
	//  0   No arguments are allowed
	//  1   Exactly one argument is required, it includes spaces
	//  *   Any number of arguments are allowed (0, 1, or many),
	//      separated by white space
	//  ?   0 or 1 arguments are allowed
	//  +   Arguments must be supplied, but any number are allowed
	NArgs string

	// Range specifies that the command accepts a range.
	//
	//  .   Range allowed, default is current line. The value
	//      "." is converted to "" for Nvim.
	//  %   Range allowed, default is whole file (1,$)
	//  N   A count (default N) which is specified in the line
	//      number position (like |:split|); allows for zero line
	//	    number.
	//
	//  :help :command-range
	Range string

	// Count specfies that thecommand accepts a count.
	//
	//  N   A count (default N) which is specified either in the line
	//	    number position, or as an initial argument (like |:Next|).
	//      Specifying -count (without a default) acts like -count=0
	//
	//  :help :command-count
	Count string

	// Addr sepcifies the domain for the range option
	//
	//  lines           Range of lines (this is the default)
	//  arguments       Range for arguments
	//  buffers         Range for buffers (also not loaded buffers)
	//  loaded_buffers  Range for loaded buffers
	//  windows         Range for windows
	//  tabs            Range for tab pages
	//
	//  :help command-addr
	Addr string

	// Eval is evaluated in Nvim and the result is passed as an argument.
	Eval string

	// Complete specifies command completion.
	//
	//  :help :command-complete
	Complete string

	// Bang specifies that the command can take a ! modifier (like :q or :w).
	Bang bool

	// Register specifes that the first argument to the command can be an
	// optional register name (like :del, :put, :yank).
	Register bool

	// Bar specifies that the command can be followed by a "|" and another
	// command.  A "|" inside the command argument is not allowed then. Also
	// checks for a " to start a comment.
	Bar bool
}

CommandOptions specifies command options.

type FunctionOptions

type FunctionOptions struct {
	// Name is the name of the function in Nvim. The name must be made of
	// alphanumeric characters and '_', and must start with a capital letter.
	Name string

	// Eval is an expression evaluated in Nvim. The result is passed the
	// handler function.
	Eval string
}

FunctionOptions specifies function options.

type Plugin

type Plugin struct {
	Nvim *nvim.Nvim
	// contains filtered or unexported fields
}

Plugin represents a remote plugin.

func New

func New(v *nvim.Nvim) *Plugin

New returns an intialized plugin.

func (*Plugin) Handle

func (p *Plugin) Handle(method string, fn interface{})

Handle registers fn as a MessagePack RPC handler for the specified method name. The function signature for fn is one of

func([v *nvim.Nvim,] {args}) ({resultType}, error)
func([v *nvim.Nvim,] {args}) error
func([v *nvim.Nvim,] {args})

where {args} is zero or more arguments and {resultType} is the type of of a return value. Call the handler from Nvim using the rpcnotify and rpcrequest functions:

:help rpcrequest()
:help rpcnotify()

func (*Plugin) HandleAutocmd

func (p *Plugin) HandleAutocmd(options *AutocmdOptions, fn interface{})

HandleAutocmd registers fn as a handler an autocmnd event.

If options.Eval == "*", then HandleAutocmd constructs the expression to evaluate in Nvim from the type of fn's last argument. See the HandleFunction documentation for information on how the expression is generated.

func (*Plugin) HandleCommand

func (p *Plugin) HandleCommand(options *CommandOptions, fn interface{})

HandleCommand registers fn as a handler for a Nvim command. The arguments to the function fn are:

v *nvim.Nvim        optional
args []string       when options.NArgs != ""
range [2]int        when options.Range == "." or Range == "%"
range int           when options.Range == N or Count != ""
bang bool           when options.Bang == true
register string     when options.Register == true
eval interface{}    when options.Eval != ""

The function fn must return an error.

If options.Eval == "*", then HandleCommand constructs the expression to evaluate in Nvim from the type of fn's last argument. See the HandleFunction documentation for information on how the expression is generated.

func (*Plugin) HandleFunction

func (p *Plugin) HandleFunction(options *FunctionOptions, fn interface{})

HandleFunction registers fn as a handler for a Nvim function. The function signature for fn is one of

func([v *nvim.Nvim,] args {arrayType} [, eval {evalType}]) ({resultType}, error)
func([v *nvim.Nvim,] args {arrayType} [, eval {evalType}]) error

where {arrayType} is a type that can be unmarshaled from a MessagePack array, {evalType} is a type compatible with the Eval option expression and {resultType} is the type of function result.

If options.Eval == "*", then HandleFunction constructs the expression to evaluate in Nvim from the type of fn's last argument. The last argument is assumed to be a pointer to a struct type with 'eval' field tags set to the expression to evaluate for each field. Nested structs are supported. The expression for the function

func example(eval *struct{
    GOPATH string `eval:"$GOPATH"`
    Cwd    string `eval:"getcwd()"`
})

is

{'GOPATH': $GOPATH, Cwd: getcwd()}

func (*Plugin) Manifest

func (p *Plugin) Manifest(host string) []byte

func (*Plugin) RegisterForTests

func (p *Plugin) RegisterForTests() error

RegisterForTests registers the plugin with Nvim. Use this method for testing plugins in an embedded instance of Nvim.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL