A server for Vim clients using the NetBeans Protocol.
An implementation of the Netbeans Protocol, a socket interface designed for Vim integration into an IDE.
vim-netbeans allows you to create servers that Vim clients can connect to. You can control the Vim clients and get notifications about what they are doing.
The protocol is named NetBeans for historical reasons, and does not actually require the NetBeans IDE or Java.
npm install vim-netbeans
var nb = require"vim-netbeans";var server = ;serveron"clientAuthed"vimon"insert"console.log"Inserted text at " + offset + ": " + text;;vimon"remove"console.log"Removed " + length + " bytes at " + offset;;;serverlisten;
example.js for a larger example.
To connect to your NetBeans server, launch Vim with
-nb or use the command
:nbs in Vim. To close the connection, Use
Host, port, and password can be specified with
Connection information can also be read from a file or environment. See the Vim Documentation.
This API is an abstraction over the Vim Netbeans Protocol, a socket interface intended for Vim integration into an IDE.
A server that listens for connections from Vim.
3219) default Vim netbeans socket port
"changeme") default password that Vim connects with
net.Server) underlying socket server
array<VimClient>) Vim clients connected to this server
http.Server) optional HTTP server for multiplexing
new VimServer([options]) - Create and configure a new Vim NetBeans server, with properties as follows:
boolean: defaults to false) If true, socket communication will be printed.
listen([port], [host], [backlog], [callback]) - Bind the server to a port.
number|string: defaults to defaultPort) the port number to bind to connections
number|string) maximum length of the queue of pending
string: defaults to any IPv4) the hostname to bind to
function) called when the port is bound to the server
See also net.Server.listen(port).
handleHTTP(server) - Multiplex HTTP on the same port as the NetBeans server.
http.Server) the HTTP server to pass requests to
VimClient) the client that connected
string) the password the client supplied
Represents a Vim program that has connected to a VimServer.
net.Socket) underlying socket connection
VimServer) the server managing this client connection
array<VimBuffer|null>) buffers we are controlling. Indexed by
buffer.id, starting at 1. Buffers that were removed have
null in their places.
disconnect() - Break the connection and quit Vim. Only send when there are no unsaved changes. See also
detach() - Break the connection without exiting the editor.
key(key, listener) - Register a function to be called when the vim user presses a certain key. Once set, a key listener cannot be removed, but you can change the listener function by calling
key(key, ...) again.
key - (
string) Key name. Supported are:
'X'any unrecognized key
The key may be prepended by
M, with a hyphen, for Control, Shift and Meta (Alt) modifiers. e.g.:
listener - (
function(buffer, offset, lnum, col)) called when the user presses the key. If
listener is not a function, the events for the given key are ignored.
VimBuffer) the buffer in which the key was pressed
number) byte offset of the cursor in the buffer
number) line number of the cursor
number) column number of the cursor
createBuffer():buffer - Create and return an unnamed buffer, and make it the current buffer for the client.
VimBuffer) the buffer created
editFile(pathname, callback) - Open a file for editing.
string) the file to edit
function(buffer)) called when the file has been opened
VimBuffer) the newly created buffer
raise() - Bring the editor to the foreground. Requires Vim with GUI.
showBalloon(text) - Display a balloon/tooltip at the mouse position, containing some text. It disappears when the mouse moves away. Requires Vim with GUI.
string) text to show in the balloon
getCursor(callback) - Get the current buffer and cursor position.
function(buffer, lnum, col, offset))
VimBuffer|null) the current buffer, or null if it is a mystery
number) - line number of the cursor (first line is one)
number) - column number of the cursor (in bytes, zero based)
number) offset of the cursor in the buffer (in bytes)
getModified(callback) - Get the number of buffers with changes
number) number of buffers with changes
saveAndExit(callback) - Ask the client to save all buffers and exit (
:confirm qall). If the user cancels this operation, the number of modified buffers is returned.
number|null) number of modified buffers, or null if the client exited and closed the connection.
newBuffer(buffer) - The client has opened a new buffer and we are claiming it. Also fired if the user presses a special key in a buffer weNot fired if the server creates the buffer with
VimBuffer) the new buffer
disconnect() - Vim is exiting.
disconnected() - The connection with the client has closed. After this event, all listeners for the client and its buffers will be removed.
fileOpened(pathname) - A file was opened by the user.
string) name of the file
startupDone() - The editor has finished its startup work and is ready for editing files.
version(version) - Reports the version of the NetBeans interface. node-vim-netbeans assumes the version is 2.5. Some functions and events do not work in older versions.
In addition to these events, a VimClient also receives events for buffers that it has control of, with the VimBuffer object added as the first argument.
This allows you to do this:
clienton"insert" ;clienton"remove" ;
instead of this:
clienton"newBuffer"bufferon"insert" ;bufferon"remove" ;;
A specific buffer in a Vim client that a VimServer controls.
VimClient) client connection that has this buffer
number) sequential buffer id, starting from 1 for each client
addAnno(type, offset):id Place an annotation at a position in the buffer.
AnnotationType) the annotation type
number) byte offset to place the annotation at.
number) Annotation ID is returned, for use with
defineAnnoType(type) Define an annotation type in the buffer. This is done automatically the first time you use the type in a buffer, but if you change the annotation type you may use this method to give the buffer the updated version.
AnnotationType) the type
removeAnno(id) Remove a previously placed annotation.
number) the annotation ID as returned from
close() Close the buffer. This leaves us without current buffer, very dangerous to use! (according to the NetBeans API docs)
editFile(pathname) Edit a file in the buffer.
string) file to edit
guard(offset, length) Mark an area in the buffer as guarded. This means it cannot be edited.
number) byte position of text in buffer to be guarded
number) length of text
insertDone() Tell Vim an initial file insert is done. This triggers Vim to print a read message.
netbeansBuffer(own) Set whether this buffer is owned by NetBeans.
save() Save the buffer. Vim should write the buffer unless one of these conditions is true:
saveDone() Tell Vim a save is done. This triggers Vim to print a save message.
setDot(offset), setDot(lnum, col) Make the buffer the current buffer and set the cursor at the specified position. If the buffer is open in another window, make that window the current window. If there are folds, they are opened to make the cursor line visible.
number) position to set cursor at
number) line number to set cursor at
number) column number to set cursor at
setFullName(pathname) Set the file name of the buffer, and make the buffer the current buffer, but do not read from the file.
string) file name
setModified(modified) Mark the buffer as modified or unmodified.
setModtime(time) Change what Vim considers as the modification time of the file.
Date) modification date object
setReadOnly() Mark the buffer as readonly.
setTitle(name) Set the title for the buffer. Unknown what this is actually useful for.
setVisible(visible) If true, go to the buffer.
boolean) whether to show the buffer or not
startDocumentListen() Mark the buffer to report insert and remove events
stopDocumentListen() Stop reporting insert and remove events for this buffer. Note: if
netbeansBuffer was used to mark this buffer as a NetBeans buffer, then the buffer is deleted in Vim.
unguard() Removing guarding for a text area. Also sets the current buffer, if necessary.
number) byte position of text to unguard
number) length of text area
getLength(callback) Get the length of the buffer in bytes.
number) length of the buffer
getCursor(callback) Get the cursor position if it is in this buffer
function(lnum, col, offset)) Values are null if this buffer is not the current buffer.
number|null) line number of the cursor (from 1)
number|null) column the cursor (in bytes, from 0)
number|null) byte offset of the cursor the buffer
getAnno(id, callback) Find an annotation in the buffer.
number) ID of the annotation, from
number) line number of the annotation
getModified(callback) Check if the buffer has changes.
boolean) whether the buffer is modified or not
getText(callback) Get the contents of the buffer
string) buffer contents
insert(offset, text, [callback]) Insert text before a position in the buffer. Sets the current buffer, if necessary. Does not move the cursor to the changed text. Resets undo information.
number) position for text. If it points to the start of a line, The text is inserted above this line. If it points after the start of a line, the text is inserted after the line.
string) the text to insert
string|null) Error message on failure, null on success
remove(offset, length, [callback]) Delete some text in the buffer.
number) position to remove text at
string) number of bytes to remove
string|null) Error message on failure, null on success
balloonText(text) - Used when
ballooneval is set and the mouse rests on some text for a moment. Requires Vim with GUI.
string) the text under the mouse pointer
buttonRelease(button, lnum, col) - Report which button was pressed and the location of the cursor at the time of the release. Only for buffers that are owned by the Vim Controller. This event is not sent if the button was released while the mouse was in the status line or in a separator line.
number?) which button was pressed
number) line number of where the mouse clicked
number) column number. If < 1, the button releas was in the sign area.
fileOpened(pathname) - The user reopened the file in the buffer, perhaps by using
string) name of the file. Should be same as
geometry(cols, rows, x, y) - Report the size and position of the editor window. Only works for Motif
number) number of text columns
number) number of text rows
number) pixel position on screen
number) pixel position on screen
insert(offset, text) - Text has been inserted in Vim. Only fired when enabled with
number) position of text in buffer
string) the inserted text.
remove(offset, length) - Text was deleted in Vim. Only fired when enabled with
number) position in buffer
number) bytes removed
killed() - The user deleted a file and the buffer has been removed. Event listeners will be cleaned up.
save() - The buffer has been saved and is now unmodified. Only fired when enabled with
unmodified() - The buffer is now unmodified. Only fired when enabled with
AnnotationTypes are used for adding text annotations with
string|null) name that identifies this annotation. (TODO: find where this is used)
string|null) Name of icon file. If one or two characters long, it defines a text sign instead.
string|number|null) foreground color for line highlighting
string|number|null) background color for line highlighting
When both fg and bg are null, no line highlighting is used.
Color values may also be "#rrggbb", or a numeric value thereof, and these are only defined for GVim.
object) see AnnotationType Properties