README

govim - Go development plugin for Vim8

Command github.com/myitcv/govim/cmd/govim (referred to simply as govim) is a Go development plugin for Vim8, much like vim-go. But unlike vim-go, govim is written in Go, not VimScript. It has features like code completion, format-on-save, hover details and go-to definition, all of which are driven by gopls, the Language Server Protocol (LSP) server for Go. See the wiki for more details. Installation instructions below.

Package github.com/myitcv/govim provides an API for plugin developers to interface with Vim8 in Go. More details here.

govim requires at least go1.12 and Vim v8.1.1158 (gvim is also supported). Neovim is not (currently) supported. More details in the FAQ.

Install govim via:

  • Vim 8 packages
    • git clone https://github.com/myitcv/govim.git ~/.vim/pack/plugins/start/govim
  • Pathogen
    • git clone https://github.com/myitcv/govim.git ~/.vim/bundle/govim
  • vim-plug
    • Plug 'myitcv/govim'
  • Vundle
    • Plugin 'myitcv/govim'

You might need some .vimrc settings to get all features working: see the minimal .vimrc for an commented explanation of the required settings. For more details on .vimrc/.gvimrc settings as well as some tips and tricks, see here.

What can govim do?

See govim plugin API which also has links to some demo screencasts.

FAQ

Top of your list of questions is likely "Why have you created govim? What is/was wrong with vim-go?" For answers this and more see FAQ.

Contributing

Contributions are very much welcome in the form of:

  • feedback
  • issues
  • PRs

See govim tests for details on how the modules in this repository are tested.

Expand ▾ Collapse ▴

Documentation

Overview

    Package govim implements a Vim8 channel-based plugin host that can be used to write plugins.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	ErrShuttingDown = errors.New("govim shutting down")
    )

    Functions

    func ParseVimVersion

    func ParseVimVersion(b []byte) (string, error)

      ParseVimVersion takes b which is assumed to be the output from :version or --version and returns the equivalent semver version.

      TODO when the minimum Vim version we require is >= v8.1.1526, then we can drop the legacy version parsing

      Types

      type CommAttr

      type CommAttr interface {
      	fmt.Stringer
      	// contains filtered or unexported methods
      }

      type CommMod

      type CommMod string
      const (
      	CommModAboveLeft    CommMod = "aboveleft"
      	CommModBelowRight   CommMod = "belowright"
      	CommModBotRight     CommMod = "botright"
      	CommModBrowse       CommMod = "browse"
      	CommModConfirm      CommMod = "confirm"
      	CommModHide         CommMod = "hide"
      	CommModKeepAlt      CommMod = "keepalt"
      	CommModKeepJumps    CommMod = "keepjumps"
      	CommModKeepMarks    CommMod = "keepmarks"
      	CommModKeepPatterns CommMod = "keeppatterns"
      	CommModLeftAbove    CommMod = "leftabove"
      	CommModLockMarks    CommMod = "lockmarks"
      	CommModNoSwapfile   CommMod = "noswapfile"
      	CommModRightBelow   CommMod = "rightbelow"
      	CommModSilent       CommMod = "silent"
      	CommModTab          CommMod = "tab"
      	CommModTopLeft      CommMod = "topleft"
      	CommModVerbose      CommMod = "verbose"
      	CommModVertical     CommMod = "vertical"
      )

      type CommModList

      type CommModList []CommMod

      func (CommModList) String

      func (c CommModList) String() string

      type CommandFlags

      type CommandFlags struct {
      	Line1 *int
      	Line2 *int
      	Range *int
      	Count *int
      	Bang  *bool
      	Reg   *string
      	Mods  CommModList
      }

      func (*CommandFlags) UnmarshalJSON

      func (c *CommandFlags) UnmarshalJSON(b []byte) error

      type Complete

      type Complete uint
      const (
      	CompleteArglist      Complete = iota // -complete=arglist
      	CompleteAugroup                      // -complete=augroup
      	CompleteBuffer                       // -complete=buffer
      	CompleteBehave                       // -complete=behave
      	CompleteColor                        // -complete=color
      	CompleteCommand                      // -complete=command
      	CompleteCompiler                     // -complete=compiler
      	CompleteCscope                       // -complete=cscope
      	CompleteDir                          // -complete=dir
      	CompleteEnvironment                  // -complete=environment
      	CompleteEvent                        // -complete=event
      	CompleteExpression                   // -complete=expression
      	CompleteFile                         // -complete=file
      	CompleteFileInPath                   // -complete=file_in_path
      	CompleteFiletype                     // -complete=filetype
      	CompleteFunction                     // -complete=function
      	CompleteHelp                         // -complete=help
      	CompleteHighlight                    // -complete=highlight
      	CompleteHistory                      // -complete=history
      	CompleteLocale                       // -complete=locale
      	CompleteMapclear                     // -complete=mapclear
      	CompleteMapping                      // -complete=mapping
      	CompleteMenu                         // -complete=menu
      	CompleteMessages                     // -complete=messages
      	CompleteOption                       // -complete=option
      	CompletePackadd                      // -complete=packadd
      	CompleteShellCmd                     // -complete=shellcmd
      	CompleteSign                         // -complete=sign
      	CompleteSyntax                       // -complete=syntax
      	CompleteSyntime                      // -complete=syntime
      	CompleteTag                          // -complete=tag
      	CompleteTagListFiles                 // -complete=tag_listfiles
      	CompleteUser                         // -complete=user
      	CompleteVar                          // -complete=var
      )

      func (Complete) String

      func (i Complete) String() string

      type CompleteCustom

      type CompleteCustom string

      func (CompleteCustom) String

      func (c CompleteCustom) String() string

      type CompleteCustomList

      type CompleteCustomList string

      func (CompleteCustomList) String

      func (c CompleteCustomList) String() string

      type CountN

      type CountN int

      func (CountN) String

      func (c CountN) String() string

      type Event

      type Event uint
      const (
      	EventBufNewFile           Event = iota // BufNewFile
      	EventBufReadPre                        // BufReadPre
      	EventBufRead                           // BufRead
      	EventBufReadPost                       // BufReadPost
      	EventBufReadCmd                        // BufReadCmd
      	EventFileReadPre                       // FileReadPre
      	EventFileReadPost                      // FileReadPost
      	EventFileReadCmd                       // FileReadCmd
      	EventFilterReadPre                     // FilterReadPre
      	EventFilterReadPost                    // FilterReadPost
      	EventStdinReadPre                      // StdinReadPre
      	EventStdinReadPost                     // StdinReadPost
      	EventBufWrite                          // BufWrite
      	EventBufWritePre                       // BufWritePre
      	EventBufWritePost                      // BufWritePost
      	EventBufWriteCmd                       // BufWriteCmd
      	EventFileWritePre                      // FileWritePre
      	EventFileWritePost                     // FileWritePost
      	EventFileWriteCmd                      // FileWriteCmd
      	EventFileAppendPre                     // FileAppendPre
      	EventFileAppendPost                    // FileAppendPost
      	EventFileAppendCmd                     // FileAppendCmd
      	EventFilterWritePre                    // FilterWritePre
      	EventFilterWritePost                   // FilterWritePost
      	EventBufAdd                            // BufAdd
      	EventBufCreate                         // BufCreate
      	EventBufDelete                         // BufDelete
      	EventBufWipeout                        // BufWipeout
      	EventTerminalOpen                      // TerminalOpen
      	EventBufFilePre                        // BufFilePre
      	EventBufFilePost                       // BufFilePost
      	EventBufEnter                          // BufEnter
      	EventBufLeave                          // BufLeave
      	EventBufWinEnter                       // BufWinEnter
      	EventBufWinLeave                       // BufWinLeave
      	EventBufUnload                         // BufUnload
      	EventBufHidden                         // BufHidden
      	EventBufNew                            // BufNew
      	EventSwapExists                        // SwapExists
      	EventFileType                          // FileType
      	EventSyntax                            // Syntax
      	EventEncodingChanged                   // EncodingChanged
      	EventTermChanged                       // TermChanged
      	EventOptionSet                         // OptionSet
      	EventVimEnter                          // VimEnter
      	EventGUIEnter                          // GUIEnter
      	EventGUIFailed                         // GUIFailed
      	EventTermResponse                      // TermResponse
      	EventQuitPre                           // QuitPre
      	EventExitPre                           // ExitPre
      	EventVimLeavePre                       // VimLeavePre
      	EventVimLeave                          // VimLeave
      	EventFileChangedShell                  // FileChangedShell
      	EventFileChangedShellPost              // FileChangedShellPost
      	EventFileChangedRO                     // FileChangedRO
      	EventDiffUpdated                       // DiffUpdated
      	EventDirChanged                        // DirChanged
      	EventShellCmdPost                      // ShellCmdPost
      	EventShellFilterPost                   // ShellFilterPost
      	EventCmdUndefined                      // CmdUndefined
      	EventFuncUndefined                     // FuncUndefined
      	EventSpellFileMissing                  // SpellFileMissing
      	EventSourcePre                         // SourcePre
      	EventSourcePost                        // SourcePost
      	EventSourceCmd                         // SourceCmd
      	EventVimResized                        // VimResized
      	EventFocusGained                       // FocusGained
      	EventFocusLost                         // FocusLost
      	EventCursorHold                        // CursorHold
      	EventCursorHoldI                       // CursorHoldI
      	EventCursorMoved                       // CursorMoved
      	EventCursorMovedI                      // CursorMovedI
      	EventWinNew                            // WinNew
      	EventTabNew                            // TabNew
      	EventTabClosed                         // TabClosed
      	EventWinEnter                          // WinEnter
      	EventWinLeave                          // WinLeave
      	EventTabEnter                          // TabEnter
      	EventTabLeave                          // TabLeave
      	EventCmdwinEnter                       // CmdwinEnter
      	EventCmdwinLeave                       // CmdwinLeave
      	EventCmdlineChanged                    // CmdlineChanged
      	EventCmdlineEnter                      // CmdlineEnter
      	EventCmdlineLeave                      // CmdlineLeave
      	EventInsertEnter                       // InsertEnter
      	EventInsertChange                      // InsertChange
      	EventInsertLeave                       // InsertLeave
      	EventInsertCharPre                     // InsertCharPre
      	EventTextChanged                       // TextChanged
      	EventTextChangedI                      // TextChangedI
      	EventTextChangedP                      // TextChangedP
      	EventTextYankPost                      // TextYankPost
      	EventColorSchemePre                    // ColorSchemePre
      	EventColorScheme                       // ColorScheme
      	EventRemoteReply                       // RemoteReply
      	EventQuickFixCmdPre                    // QuickFixCmdPre
      	EventQuickFixCmdPost                   // QuickFixCmdPost
      	EventSessionLoadPost                   // SessionLoadPost
      	EventMenuPopup                         // MenuPopup
      	EventCompleteDone                      // CompleteDone
      )

      func (Event) String

      func (i Event) String() string

      type Events

      type Events []Event

      type Flavor

      type Flavor uint
      const (
      	FlavorVim    Flavor = iota // vim
      	FlavorGvim                 // gvim
      	FlavorNeovim               // neovim
      )

      func (Flavor) String

      func (i Flavor) String() string

      type GenAttr

      type GenAttr uint
      const (
      	AttrBang     GenAttr = iota // -bang
      	AttrBar                     // -bar
      	AttrRegister                // -register
      	AttrBuffer                  // -buffer
      )

      func (GenAttr) String

      func (i GenAttr) String() string

      type Govim

      type Govim interface {
      	// ChannelEx executes a ex command in Vim
      	ChannelEx(expr string) error
      
      	// ChannelExpr evaluates and returns the result of expr in Vim
      	ChannelExpr(expr string) (json.RawMessage, error)
      
      	// ChannelNormal run a command in normal mode in Vim
      	ChannelNormal(expr string) error
      
      	// ChannelCall evaluates and returns the result of call in Vim
      	ChannelCall(fn string, args ...interface{}) (json.RawMessage, error)
      
      	// ChannelRedraw performs a redraw in Vim
      	ChannelRedraw(force bool) error
      
      	// DefineFunction defines the named function in Vim. name must begin with a capital
      	// letter. params is the parameters that will be used in the Vim function delcaration.
      	// If params is nil, then "..." is assumed.
      	DefineFunction(name string, params []string, f VimFunction) error
      
      	// DefineRangeFunction defines the named function as range-based in Vim. name
      	// must begin with a capital letter. params is the parameters that will be used
      	// in the Vim function delcaration.  If params is nil, then "..." is assumed.
      	DefineRangeFunction(name string, params []string, f VimRangeFunction) error
      
      	// DefineCommand defines the named command in Vim. name must begin with a
      	// capital letter. attrs is a series of attributes for the command; see :help
      	// E174 in Vim for more details.
      	DefineCommand(name string, f VimCommandFunction, attrs ...CommAttr) error
      
      	// DefineAutoCommand defines an autocmd for events for files matching patterns.
      	DefineAutoCommand(group string, events Events, patts Patterns, nested bool, f VimAutoCommandFunction, exprs ...string) error
      
      	// Run is a user-friendly run wrapper
      	Run() error
      
      	// DoProto is used as a wrapper around function calls that jump the "interface"
      	// between the user and protocol aspects of govim.
      	DoProto(f func() error) error
      
      	// Viewport returns the active Vim viewport
      	Viewport() (Viewport, error)
      
      	// Errorf raises a formatted fatal error
      	Errorf(format string, args ...interface{})
      
      	// Logf logs a formatted message to the logger
      	Logf(format string, args ...interface{})
      
      	// Scheduled returns the event queue Govim interface
      	Scheduled() Govim
      
      	// Schedule schdules f to run in the event queue
      	Schedule(func(Govim) error) chan struct{}
      
      	// Flavor returns the flavor of the editor to which the Govim instance is
      	// connected
      	Flavor() Flavor
      
      	// Version returns the semver version of the editor to which the Govim
      	// instance is connected
      	Version() string
      
      	// Loaded returns a channel that can be used to wait until a Govim instance
      	// has finished loading. The Init phase will follow a successful load.
      	Loaded() chan struct{}
      
      	// Initialized returns a channel that can be used to wait until a Govim
      	// instance has completed the init phase, post loading.
      	Initialized() chan struct{}
      
      	// Shutdown returns a channel that can be used to wait until a Govim
      	// instance has completed the shutdown phase.
      	Shutdown() chan struct{}
      }

      func NewGovim

      func NewGovim(plug Plugin, in io.Reader, out io.Writer, log io.Writer) (Govim, error)

      type NArgs

      type NArgs uint
      const (
      	NArgs0          NArgs = iota // -nargs=0
      	NArgs1                       // -nargs=1
      	NArgsZeroOrMore              // -nargs=*
      	NArgsZeroOrOne               // -nargs=?
      	NArgsOneOrMore               // -nargs=+
      )

      func (NArgs) String

      func (i NArgs) String() string

      type Pattern

      type Pattern string

      type Patterns

      type Patterns []Pattern

      type Plugin

      type Plugin interface {
      	Init(Govim, chan error) error
      	Shutdown() error
      }

        Plugin defines the contract between github.com/myitcv/govim and a plugin.

        type Range

        type Range uint
        const (
        	RangeLine Range = iota // -range
        	RangeFile              // -range=%
        )

        func (Range) String

        func (i Range) String() string

        type RangeN

        type RangeN int

        func (RangeN) String

        func (r RangeN) String() string

        type SwitchBufMode

        type SwitchBufMode string

          SwitchBufValue typed constants define the set of values that the Vim setting switchbuf can take. See :help switchbuf for more details and definitions of each value.

          const (
          	SwitchBufUseOpen SwitchBufMode = "useopen"
          	SwitchBufUseTag  SwitchBufMode = "usetab"
          	SwitchBufSplit   SwitchBufMode = "split"
          	SwitchBufVsplit  SwitchBufMode = "vsplit"
          	SwitchBufNewTab  SwitchBufMode = "newtab"
          )

          func ParseSwitchBufModes

          func ParseSwitchBufModes(vs string) ([]SwitchBufMode, error)

            ParseSwitchBufModes assumes vs is a valid value for &switchbuf

            type Viewport

            type Viewport struct {
            	Current WinInfo
            	Windows []WinInfo
            }

            type VimAutoCommandFunction

            type VimAutoCommandFunction func(g Govim, args ...json.RawMessage) error

              VimAutoCommandFunction is the signature of a callback from a defined autocmd

              type VimCommandFunction

              type VimCommandFunction func(g Govim, flags CommandFlags, args ...string) error

                VimCommandFunction is the signature of a callback from a defined command

                type VimFunction

                type VimFunction func(g Govim, args ...json.RawMessage) (interface{}, error)

                  VimFunction is the signature of a callback from a defined function

                  type VimRangeFunction

                  type VimRangeFunction func(g Govim, line1, line2 int, args ...json.RawMessage) (interface{}, error)

                    VimRangeFunction is the signature of a callback from a defined range-based function

                    type WinInfo

                    type WinInfo struct {
                    	WinNr    int
                    	BotLine  int
                    	Height   int
                    	BufNr    int
                    	WinBar   int
                    	Width    int
                    	TabNr    int
                    	QuickFix bool
                    	TopLine  int
                    	LocList  bool
                    	WinCol   int
                    	WinRow   int
                    	WinID    int
                    	Terminal bool
                    }

                    func (*WinInfo) UnmarshalJSON

                    func (wi *WinInfo) UnmarshalJSON(b []byte) error

                    Directories

                    Path Synopsis
                    cmd
                    govim
                    Command govim is a Vim8 channel-based plugin, written in Go, to support the writing of Go code in Vim8
                    Command govim is a Vim8 channel-based plugin, written in Go, to support the writing of Go code in Vim8
                    govim/config
                    Package config declares the configuration variables, functions and commands used by govim
                    Package config declares the configuration variables, functions and commands used by govim
                    govim/internal/fastwalk
                    Package fastwalk provides a faster version of filepath.Walk for file system scanning tools.
                    Package fastwalk provides a faster version of filepath.Walk for file system scanning tools.
                    govim/internal/gopathwalk
                    Package gopathwalk is like filepath.Walk but specialized for finding Go packages, particularly in $GOPATH and $GOROOT.
                    Package gopathwalk is like filepath.Walk but specialized for finding Go packages, particularly in $GOPATH and $GOROOT.
                    govim/internal/imports
                    Package imports implements a Go pretty-printer (like package "go/format") that also adds or removes import statements as necessary.
                    Package imports implements a Go pretty-printer (like package "go/format") that also adds or removes import statements as necessary.
                    govim/internal/jsonrpc2
                    Package jsonrpc2 is a minimal implementation of the JSON RPC 2 spec.
                    Package jsonrpc2 is a minimal implementation of the JSON RPC 2 spec.
                    govim/internal/lsp/browser
                    Package browser provides utilities for interacting with users' browsers.
                    Package browser provides utilities for interacting with users' browsers.
                    govim/internal/lsp/cmd
                    Package cmd handles the gopls command line.
                    Package cmd handles the gopls command line.
                    govim/internal/lsp/diff
                    Package diff implements the Myers diff algorithm.
                    Package diff implements the Myers diff algorithm.
                    govim/internal/lsp/fuzzy
                    Package fuzzy implements a fuzzy matching algorithm.
                    Package fuzzy implements a fuzzy matching algorithm.
                    govim/internal/lsp/protocol
                    Package protocol contains the structs that map directly to the wire format of the "Language Server Protocol".
                    Package protocol contains the structs that map directly to the wire format of the "Language Server Protocol".
                    govim/internal/lsp/snippet
                    Package snippet implements the specification for the LSP snippet format.
                    Package snippet implements the specification for the LSP snippet format.
                    govim/internal/lsp/source
                    Package source provides core features for use by Go editors and tools.
                    Package source provides core features for use by Go editors and tools.
                    govim/internal/lsp/telemetry
                    Package telemetry provides the hooks and adapters to allow use of telemetry throughout gopls.
                    Package telemetry provides the hooks and adapters to allow use of telemetry throughout gopls.
                    govim/internal/lsp/telemetry/metric
                    Package metric aggregates stats into metrics that can be exported.
                    Package metric aggregates stats into metrics that can be exported.
                    govim/internal/lsp/telemetry/stats
                    Package stats provides support for recording telemetry statistics.
                    Package stats provides support for recording telemetry statistics.
                    govim/internal/lsp/telemetry/tag
                    Package tag provides support for telemetry tagging.
                    Package tag provides support for telemetry tagging.
                    govim/internal/lsp/telemetry/trace
                    Package tag adds support for telemetry tracing.
                    Package tag adds support for telemetry tracing.
                    govim/internal/lsp/telemetry/worker
                    Package worker provides a very simple mechanism to allow telemetry packages to work cooperatively and efficiently.
                    Package worker provides a very simple mechanism to allow telemetry packages to work cooperatively and efficiently.
                    govim/internal/memoize
                    Package memoize supports memoizing the return values of functions with idempotent results that are expensive to compute.
                    Package memoize supports memoizing the return values of functions with idempotent results that are expensive to compute.
                    govim/internal/module
                    Package module defines the module.Version type along with support code.
                    Package module defines the module.Version type along with support code.
                    govim/internal/semver
                    Package semver implements comparison of semantic version strings.
                    Package semver implements comparison of semantic version strings.
                    govim/internal/tool
                    Package tool is an opinionated harness for writing Go tools.
                    Package tool is an opinionated harness for writing Go tools.
                    govim/internal/txtar
                    Package txtar implements a trivial text-based file archive format.
                    Package txtar implements a trivial text-based file archive format.
                    govim/internal/xcontext
                    Package xcontext is a package to offer the extra functionality we need from contexts that is not available from the standard context package.
                    Package xcontext is a package to offer the extra functionality we need from contexts that is not available from the standard context package.
                    internal
                    Package testdriver is a support package for plugins written using github.com/myitcv/govim
                    Package testdriver is a support package for plugins written using github.com/myitcv/govim