Vimtron-io NPM

Vimtron IO

Control and interact with VIM from Node. This module is used by Vimtron and requires vimtron.vim plugin.

Install

npm i vimtron-io

Also you will need to install vimtron.vim plugin

Config

Vimtron.vim looks for $VIMTRON_PORT environment variable to connect to the server. Vimtron does this automagically but if you're not using Vimtron you will need to set it manually.

Example

In Node

const { connect, on, call, ex, normal, redraw } = require('vimtron-io')

on('test', function* () {
  const cwd = yield call.getcwd()
  ex(`e ${cwd}/secretfile.txt`)
  normal('gg')
  redraw()
})

connect(1234)

In VIM (using Vimtron.vim)

:IDE test

API

Requiring this module returns an object with the following methods:

`connect(port, readyFn)`

Start server on the following port. In Vim you can connect to the specified port with ch_open()

port integer - what port the server should listen on
readyFn function (optional) - callback function for when the server has started

`on(event, callback)`

event string - name of event to listen to. Corresponds to Vimtron vim plugin command argument e.g. :Vimtron myEventNameHere
callback function - callback function to be called whenever server receives data on event namespace. Callback function receives:
- data object|string|number|array - data received from VIM

`onError(callback)`

callback function - register callback to be called whenever server throws an error

`onConnect(callback)`

callback function - callback when client connects. Note: server will buffer any commands you send until the server connects. This method is more of a bonus than a requirement

`onClose(callback)`

callback function - callback when client disconnects

`redraw(force)`

Redraw the screen. Vim does not automatically redraw the screen on some commands. This allows servers talking over channels to send multiple commands before redrawing. For example, opening a file ex('e ~/stuff.txt') won't display the opened file until you also call redraw()

force bool (optional) - clear the screen first

`normal(command)`

Execute a normal command in VIM

command string - equivalent to normal! in Vim

`ex(command)`

Execute an ex command in VIM

command string - commands... you know, like :e /project/myfile.txt

`expr(expression)`

Execute an expression in VIM and return the result via a Promise. Can be used with generator functions.

expression string - expression to execute. Returns expression result. If the expression fails or the encode/transmit from Vim fails, the result will be undefined

Example:

on('ello', function* () {
  const buffer = yield expr(`getline(1, '$')`)
  console.log(buffer.join('\n'))
})

`call.`

Execute a VIM function specified after the dot with the arguments and return the result via a Promise. call. is a Proxy so any getter property invoked on call. will be used as the name of the Vim function.

Example:

on('ello', function* () {
  const length = yield call.strlen('sith')
  console.log(length)
})

`define.`

Define a Vimscript function to be loaded globally. Sometimes it's easier to execute a function in Vim that deals with a lot of Vim internal API than to send-receive between client-server. define. is a Proxy so any getter property invoked on define. will be used as the name of the Vim function. Note: names will be converted to pascal case in case you provide camel cased names.

Example:

define.GetBuffers(`
  let all = range(0, bufnr('$'))
  let current = bufnr('%')
  let res = []
  for b in all
    if buflisted(b) && b != current
      call add(res, bufname(b))
    endif
  endfor
  return res
`)

on('buffers', function* () {
  const buffers = yield call.GetBuffers()
  console.log(buffers)
})

`autocmd.`

Register a callback whenever a Vim autocmd is triggered. Like call and define this is a Proxy so getter properties are used as the autocmd event name. Note: camel case -> pascal case internally.

Example:

autocmd.insertEnter(m => {
  console.log('vim entered insert mode')
})

autocmd.winEnter('javascript', m => {
  console.log('vim entered a window that has a javascript file')
})

`until.`

Register a one-time subscription to a Vim autocmd event and return a Promise. This is also a Proxy so getter properties are used as the autocmd event name. Note: camel case -> pascal case.

Example:

on('what-changed', function* () {
  call.feedkeys('ciw')
  yield until.insertLeave()
  const insertedText = yield expr('@.')
  console.log('you just inserted:', insertedText)
})